Before you begin

Set these up once from the dashboard. What each path needs differs — and a REST transaction needs more to complete than it needs to authenticate. The HTTP API key authenticates the structured transaction call (e.g. POST /transaction/sale/pos); completing the transaction additionally depends on a client certificate and a live mTLS TCP connection held open by your fintech backend as the responder.

Prerequisite	REST (structured transaction routes)	ISO 8583 over mTLS TCP	HSMaaS (payShield) over mTLS TCP
API key (sk_live_…)	Required — authenticates the HTTP call	Not used	Not used
Client certificate	Required for the responder connection that completes the transaction, not for the HTTP call itself	Required — your org’s identity on the TCP interface	Required — your org’s identity on the TCP interface
Live mTLS TCP connection	Required — your fintech backend must be connected as the responder, or delivery fails with 502	Required — you open it to send	Required — you open it to send
Scenario behaviour	Optional — selects a simulated outcome; keyed by network + BIN prefix, matched on the PAN	Optional — selects a simulated outcome; keyed by network + BIN prefix, matched on the PAN	Optional, and only for PAN-bearing commands — B2 echo and other commands without a PAN always use normal processing

Each transport also needs an active trial or subscription for its product: Visa for the REST routes and port 11012, Mastercard for 11013, and HSM for 11014. Without one, REST calls return 403 (product_not_entitled), and the TCP listener drops the connection (see Errors and rejections). Trials are covered in Products and trials.

The REST call itself needs only the API key; a scenario behaviour is optional and, when absent, the engine runs its normal faithful processing. Exercising the full round trip additionally needs your fintech backend connected over mTLS as the responder (client certificate + live connection); without it the structured transaction route returns 502. See Delivery needs a live TCP connection.

Every step below applies to a single organization. If your account belongs to more than one, choose the target org in the Active organization switcher in the top bar before you start — it is disabled when you have only one membership. The sidebar entries (API Keys, Certificates, Behaviours) are gated by read permissions: an entry your role lacks the scope for stays visible but greyed out and non-navigable, and each create action needs a further permission called out below. Ask an organization admin if an entry is greyed out or a create action is refused.

API key

The API key authenticates REST calls to the structured transaction routes (e.g. POST /transaction/sale/pos).

1. In the dashboard, open API Keys (needs apikeys:read; creating a key also needs apikeys:write).
2. Click Create key, select the scopes it may use, and optionally set a rate limit and IP allowlist. Dashboard-created keys are always live-environment keys — there is no environment to choose.
3. Copy the sk_live_… value. It is shown once — only a hash is stored, so a lost key cannot be recovered and must be replaced.

The API key is a Control Plane Service (CPS) product credential. It is not an OIDC token, and a Logto-issued JWT is not accepted in its place on the structured transaction routes.

Client certificate

Required for the ISO 8583 and HSMaaS TCP transports. Also required for a REST transaction to complete — not to authenticate the structured transaction call, but for the mTLS connection your fintech backend keeps open as the responder. See Delivery needs a live TCP connection.

The client certificate is your organization’s identity on the TCP interface. CPS manages issuance; KMS signs it as the certificate authority. SMP resolves your org_id from the certificate fingerprint when the connection is established.

1. In the dashboard, open Certificates (needs certs:read; issuing a certificate also needs certs:issue).

2. Click Issue certificate. The Issue certificate dialog has three optional fields:

   • Name — a friendly label shown in the Certificates list (for example acme-prod). It is independent of the subject DN and can be changed later with Rename in the Certificates table.
   • Subject / DN — an X.500 DN like CN=acme,OU=prod to embed in the certificate; left blank, CPS applies the org-derived subject CN.
   • Validity (days) — left blank, CPS applies a 365-day validity.

   Submit with Issue.

3. The result view then shows, exactly once:

   • Certificate (PEM) — the signed client certificate (certificate_pem in the issuance response).
   • Private key (PEM) — private_key_pem, returned only at issuance and never stored by CPS. A lost key cannot be recovered; re-issue instead.
   • Fingerprint (SHA-256) — fingerprint; SMP resolves your org from this value on the mTLS data plane.

4. The same view has a Connection details section — the data-plane Host and one row per fixed service port: Visa ISO 8583 (11012), Mastercard ISO 8583 (11013), and HSMaaS (payShield) (11014). The host is not part of the issuance response; the dashboard supplies it. Point your client at host:port, presenting this certificate over mTLS.

5. Click Done to close the dialog. The private key is not shown again.

Revoking a certificate in CPS flips its status. The next mTLS handshake — and the next /api/resolve-cert lookup — then resolves to a revoked status and the connection is rejected.

Server trust root

Prerequisite for the ISO 8583 and HSMaaS TCP transports only. Not needed for REST — the structured transaction routes are served over ordinary web PKI that your HTTP client already trusts.

mTLS authenticates both ends of the TCP connection, and the two directions chain to two different Switchbench roots:

Direction	What is checked	Trust anchor you need
SMP authenticates you	the client certificate you present (above)	none on your side — SMP pins the Switchbench client CA root internally
you authenticate SMP	the server certificate SMP presents in the TLS handshake	the Switchbench server CA root, which you add to your client’s trust store

The two roots are deliberately isolated: the client CA signs only customer client certificates, the server CA signs only Switchbench’s own listener certificates, and neither root can issue the other’s identities. Verifying the SMP handshake therefore needs the server CA root — not the client CA root, and not your client certificate.

• It is environment-scoped. The test data plane (test-tcp.switchbench.com) and production (tcp.switchbench.com) chain to different server CA roots; use the one for the environment you connect to.
• It is public material. The server CA root is a certificate only — it never contains a private key. Verifying a handshake never requires a CA private key and never requires disabling certificate verification.
• Where to get it. Switchbench supplies the server CA root PEM for your target environment during onboarding, together with the connection details. If it was not included with your connection details, request it from your Switchbench onboarding contact. Save it as, for example, switchbench-server-ca-test.pem and pass it to your TLS client as the trust anchor for the data-plane host — the transport guides use openssl’s -CAfile for this.

Scenario behaviour

A scenario behaviour is an optional override: configure one only when you need a specific simulated outcome (a decline, a timeout, a partial approval) for a given card. With no behaviour in play the engine runs its normal faithful processing, so you can send REST, ISO 8583, and PAN-bearing HSMaaS traffic without setting one up at all.

Behaviours decide the business outcome Switchbench returns for a card. They are owned by the Behaviour Control Service (BCS) and are keyed by network + BIN prefix, so one definition serves the engine whether it is acting as issuer (responding) or acquirer (originating).

1. In the dashboard, open Behaviours (needs behaviours:read; adding or editing one also needs behaviours:write).
2. Click New behaviour and fill in the dialog:
   • Network — visa, mastercard, or hsm.
   • BIN prefix — the card-number prefix to match, for example 424242.
   • Action — one of the actions the selected network supports (approve, decline, timeout, partial_approval, and similar).
   • Response code (optional) — card networks only, for example 05 on a decline; left blank it falls back to the action’s default.
   • Priority (default 100) — the tie-breaker between rules whose BIN prefixes are the same length; higher wins.
   • Enabled — leave checked for the rule to take effect.
   • Any action-specific parameters the form then asks for.
3. Click Create to save the behaviour.

Lookup is a longest-prefix match on the PAN; among equal-length prefixes the highest priority wins. BCS is off the data plane: engines poll it on a TTL and serve transactions from a locally cached snapshot, so a new or changed behaviour takes effect after the next engine refresh rather than instantly. If no behaviour matches the card, the engine runs its normal faithful behaviour.

On the hsm network the same PAN keying applies, so only payShield commands that carry a clear PAN (for example a CVV/CVC verification) can match a rule. Commands with no PAN — B2 echo test and the rest — always use normal processing; no behaviour rule and no Behaviours permission is needed to run them.

Remember the split: the behaviour you configure here selects the outcome; wire fidelity around that outcome is always computed.