API integration
What “initiating a test” means
Section titled “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 (
POST /transaction) — Switchbench is on the originating side. It asks the Visa or Mastercard engine to prepare an outbound authorization, 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). - Inbound ISO 8583 over mTLS TCP (guides planned) — Switchbench acts as the issuer/network on the other side: it validates the message, applies the configured behaviour, computes fidelity, and returns the response itself.
In both directions the same two rules govern the result:
- Fidelity is computed. ISO 8583 framing and the cryptographic artefacts (PIN, MAC, CVV/iCVV, ARQC/ARPC) are calculated on every message. You do not configure them.
- Behaviour is configured. The business outcome — approve, decline, partial approval, timeout, and similar — is selected from the behaviour you defined for that card number / BIN range. It is configured separately from message fidelity.
Before you start
Section titled “Before you start”Every transport needs the credentials and scenario setup described in Before you begin. Read that page first.
Transport guides
Section titled “Transport guides”| Guide | Transport | Auth | Status |
|---|---|---|---|
| Initiating a test transaction over REST | POST /transaction over HTTPS | API key | Available |
| Visa ISO 8583 over mTLS TCP | Port 11012 | Client certificate | Planned |
| HSMaaS (raw payShield) over mTLS TCP | Port 11014 | Client certificate | Available |
| Mastercard ISO 8583 over mTLS TCP | Port 11013 | Client certificate | Planned |
REST is the simplest entry point — an API key and a single HTTP call, with no mTLS — and is the natural first integration. The ISO 8583 and HSMaaS transports require a client certificate and a live mTLS TCP connection to the FRP edge.
For the field-by-field contract of POST /transaction — request and response
schemas, every error status with its RFC 7807 body — see the
API reference.