API integration

What “initiating a test” means

You originate an authorization into Switchbench exactly as your real system would originate one toward a payment network. What Switchbench does with it depends on the transport:

• REST (structured transaction routes, e.g. POST /transaction/sale/pos) — Switchbench is on the originating side. It asks the Visa engine to prepare an outbound authorization from your typed JSON fields, sends it over your active mTLS TCP connection to your fintech backend, waits for that backend’s response, and finalizes it into the REST response you receive. Your fintech backend is the responder, so a live mTLS connection must already be open (see Before you begin). The routes accept requests today, but the end-to-end round trip is not runnable yet (#533).
• Inbound ISO 8583 over mTLS TCP — Switchbench would act as the issuer/network on the other side: validate the message, apply the configured behaviour, compute fidelity, and return the response itself. This direction is not yet available — SMP has no inbound framing loop routing fintech-initiated frames to SVE/SME (#538), and no guide is published for it. Unsolicited inbound frames are logged and discarded.

The same two rules govern the result, within the flows that run today:

• Fidelity is computed — for the supported flows. ISO 8583 framing and the prepare-leg cryptographic artefacts for the supported Visa server-first authorization are calculated by the engine; you do not configure them. Response-leg crypto (PIN-change confirmation, key-exchange finalization) is not yet wired (#549), and PIN operations accept clear PIN digits only (#536). Mastercard scheme-specific fidelity, including its own SHE crypto integration, reaches parity with Visa as separate work (#539). The direct HSMaaS / payShield path (port 11014) is unaffected by these and runs today.
• Behaviour is optional. The business outcome — approve, decline, partial approval, timeout, and similar — is selected from a behaviour you define for that card number / BIN range, configured separately from message fidelity. Without one the engine runs its normal faithful processing; configure a behaviour only when you want a specific simulated outcome.

Before you start

Every transport needs the credentials described in Before you begin, which carries a per-path prerequisites table, plus an optional scenario behaviour when you want a specific simulated outcome. Note in particular that a REST transaction needs an API key to authenticate the structured transaction call but also a client certificate and a live mTLS TCP connection — held open by your fintech backend as the responder — to complete. Read that page first.

Current limitations

Caution

Guide availability, transport availability, and runnable transaction capabilities are three separate things. Before you build against any example below:

• REST structured transaction routes accept requests today, but the end-to-end round trip — REST originate → delivery over your mTLS TCP connection → finalize — is blocked on #533. A pure-REST caller with no active mTLS connection for the org gets a 502 on the delivery leg.
• Client-initiated (inbound) ISO 8583 on ports 11012 / 11013 is not routed to SVE/SME yet (#538); unsolicited inbound frames are logged and discarded.
• Visa (11012) exposes only the server-first delivery leg, currently exercised in isolation. Response-leg crypto is unimplemented (#549), and PIN operations accept clear PIN digits only (#536).
• Mastercard (11013) has a placeholder guide only; SME scheme fidelity — including its SHE crypto integration (#539) — is still being brought to parity with Visa.
• HSMaaS / payShield (11014) is runnable end to end; it documents the canonical payShield command subset SHE implements, not the full field-level spec.

Each transport guide’s own “What is supported today” section is the authoritative statement of runtime behaviour.

Transport guides

The Docs column is how complete the written guide is; Runtime is what actually executes today.

Guide	Transport	Auth	Docs	Runtime
Initiating a test transaction over REST	Structured transaction routes over HTTPS	API key	Complete	Routes live; full round trip blocked (#533)
Visa ISO 8583 over mTLS TCP	Port 11012	Client certificate	Complete	Server-first delivery leg only, in isolation; client-initiated auth not routed (#538); end-to-end blocked (#533)
HSMaaS (raw payShield) over mTLS TCP	Port 11014	Client certificate	Complete	Runnable end to end; canonical payShield command subset only
Mastercard ISO 8583 over mTLS TCP	Port 11013	Client certificate	Placeholder	Same mTLS/framing as Visa; client-initiated routing (#538) and SME scheme + SHE crypto fidelity (#539) pending

REST is the simplest entry point — an API key and a single HTTP call, with no mTLS on the call itself — and is the natural first integration. Completing a REST transaction still depends on your fintech backend holding a live mTLS TCP connection open as the responder, so a full round trip also needs a client certificate; a pure-REST caller with no live connection gets a 502 delivery error. The ISO 8583 and HSMaaS transports require a client certificate and a live mTLS TCP connection to the FRP edge that you open yourself.

For the field-by-field contract of the structured transaction routes — request and response schemas, every error status with its RFC 7807 body — see the API reference.