Before you begin

Set these up once from the dashboard. The REST guide needs only the API key and a behaviour; the ISO 8583 and HSMaaS transports also need a client certificate.

API key

The API key authenticates REST calls to POST /transaction.

1. In the dashboard, open API Keys.
2. Create a key for the live environment and select its scopes.
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 POST /transaction.

Client certificate

Prerequisite for the ISO 8583 and HSMaaS TCP transports only. Not needed for REST.

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 Org Settings and go to client certificates.
2. Request a client certificate for the org.
3. The issuance screen 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 screen lists the connection details separately — the data-plane host and the fixed service ports (11012 Visa, 11013 Mastercard, 11014 HSMaaS). The host is not part of the issuance response; the dashboard supplies it. Point your client at host:port, presenting this certificate over mTLS.

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.

Scenario behaviour

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

1. In the dashboard, open BCS — Behaviours.
2. Add a behaviour keyed by a card number or BIN range — for example 424242 → decline with response code 05.
3. Choose the action (approve, decline, timeout, partial_approval, and similar) and any parameters it requires.

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.

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