Environments and test data

There are three environments. Only one of them moves money.

Development and sandbox both reach the processors' own test systems, so a transaction gets a real processor response without any funds moving. Build against one of them until you are ready to go live.

Your API key and client ID are issued per environment. A production key does not work against sandbox, and the reverse. See Authentication.

Requests you send from the API reference go to a mock server, not to any of the environments above. The mock replies from the examples written into the API description, so what comes back is well formed and correctly shaped but entirely made up.

That is deliberate: a public documentation page must not be able to push a transaction into a live processor.

Two things follow from it.

• Values in a mock response are illustrative. Identifiers, auth codes, and timestamps are sample data. Never carry one into a real integration.
• The mock echoes what you send. Edit amount in the request and the same amount comes back, so you can see the shape of a response for your own values.

By default the mock returns the first response example for an operation. To ask for a specific one, name it in a header:

x-redocly-response-body-example: saleDeclined

That is how you see a declined body without a real decline.

Against the real gateway, no test card number causes a decline. Declines come from the issuer's own test system and depend on the processor configuration behind your merchant account, not on which test PAN you pick.

If you have seen a table of "decline simulation" card numbers elsewhere, it was wrong. To exercise your decline handling, use the mock and the header above, or ask your implementation contact to arrange a decline on the processor side.

Test card numbers, their CVV values, and the address to use for AVS testing are in Test cards and test accounts. All of them use expiry 12/28.

Never send a real card number to development or sandbox.

Work through this before you switch the base URL:

1. Swap the base URL for the production host.
2. Swap in your production API key and client ID.
3. Confirm you branch on result, not on the HTTP status. See Handle declines.
4. Confirm your retry logic distinguishes a 500 from a 502. See Errors and retries.
5. Confirm no log line anywhere in your stack holds a full card number, a CVV, or a bank account number.
6. Send one small live transaction and refund it.

Worth knowing before you design around them:

• No webhooks. The API sends no outbound notifications. Poll GET /v1/transactions for state that arrives after the response, such as settlement or an ACH return.
• No idempotency key. Retrying a POST /v1/transactions that already succeeded creates a second transaction. Reconcile before retrying a payment.
• No 3-D Secure. There is no field to carry a 3DS result.