Behaviours

The Behaviours page (/visa/behaviours, /mastercard/behaviours, or /hsm/behaviours) is where you author simulation behaviours — the core mechanism that lets Switchbench act as a faithful synthetic network while still letting you force specific, repeatable responses for testing.

What a behaviour is

A behaviour is a rule, owned by the Behaviour Control Service (BCS), that tells an engine — SVE (Visa), SME (Mastercard), or SHE (HSM) — how to respond instead of running its normal simulation logic. Engines poll BCS for their org’s behaviours on a fixed interval and cache them locally; a behaviour lookup never blocks a live transaction, so changes take effect after the next poll, not immediately.

Each behaviour is defined by a network, a BIN prefix (a card-number range), and an action — what the engine should do when a transaction’s PAN falls in that range on that network.

Action	Meaning	Networks	Response code	Parameters
passthrough	No override — the engine runs its normal simulation. Useful for carving an exception out of a broader range.	visa, mastercard, hsm	not allowed	none
approve	Force approval.	visa, mastercard	optional (default 00)	none
decline	Force decline.	visa, mastercard	optional (default 05)	none
refer	Refer to the card issuer.	visa, mastercard	optional (default 01)	none
partial_approval	Approve part of the requested amount.	visa, mastercard	optional (default 10)	exactly one of approvedAmount (minor units) or approvedFraction (0 < f < 1)
timeout	Don’t respond within the customer’s timeout window.	visa, mastercard, hsm	not allowed	optional delayMs
delay	Respond normally, but after a delay.	visa, mastercard, hsm	optional (card networks only)	required delayMs
error	HSM-only: force a payShield command error instead of a successful response.	hsm	not applicable	optional errorCode

The hsm network has no ISO 8583 response code, so the card-only actions (approve, decline, refer, partial_approval) aren’t offered when you select it — the form only ever shows actions the selected network supports.

How network and BIN-range scoping works

A behaviour applies to a transaction only when both match:

• Network — which engine looks the behaviour up: visa (SVE), mastercard (SME), or hsm (SHE).
• BIN prefix — a prefix of the card number. Lookup is longest-prefix match: the most specific prefix that matches a transaction’s PAN wins. For example, a 424242 behaviour takes precedence over a 4242 behaviour for a card starting 424242..., even if both are enabled.

Because (network, bin_prefix) is unique per org, two behaviours on the same network never share a BIN prefix — so for any given transaction, longest-prefix match always identifies a single applicable behaviour; there’s no same-length tie for it to break. The Priority column is a reserved tie-breaker in the underlying lookup, but it has no observable effect today given that uniqueness constraint. The page’s table is still ordered by longest prefix first (then priority, then prefix) within each network, so the row nearest the top of a network’s group is the one that actually applies to a matching transaction.

Disabled behaviours are skipped during lookup, so you can stage a rule without it taking effect — toggle it on later, or from the row’s Enable/Disable action.

Create, edit, and delete

• New behaviour opens a form scoped to your org. The network is set by the page you opened (Visa, Mastercard, or HSM), and it narrows the action choices and clears any response code or parameters that wouldn’t apply to the selection. Most actions need no parameters; partial_approval, timeout, delay, and error show additional fields driven by the same validation rules BCS enforces server-side, so the form only ever lets you submit a combination BCS will accept. An advanced JSON mode is available for editing parameters directly.
• Edit reopens the same form pre-filled for an existing behaviour.
• Enable / Disable on a row is a quick toggle that doesn’t open the full form.
• Delete asks for confirmation, then removes the behaviour.
• Like Engine Config, the page is read-only when the network’s product has lapsed (no active trial or subscription); changes are refused with 403 (product_not_entitled). See Products and trials.

Row-Level Security scopes every read and write to your organization — you can only see and change your own org’s behaviours.

Import and export

• Export downloads your org’s behaviours as a JSON file, in the same shape BCS’s import endpoint accepts — so it round-trips. Only the network filter is honored; the state and BIN prefix filters are not — export includes rows a narrowed table view may be hiding.
• Import uploads a previously exported JSON file (up to 500 rows). By default, if any row’s (network, bin_prefix) pair already exists, the whole import is rejected with a conflict so you don’t silently overwrite rules. Turn on Replace existing to upsert instead, overwriting any matching rows.

See also

• TCP Visa (ISO 8583) integration and TCP Mastercard (ISO 8583) integration document the wire format of the transactions these behaviours affect.