Testing your integration

How the triggers work

Route a merchant to the sandbox processor, then provoke a case in one of two ways. Most cases key off the transaction amount: the cents pick the outcome, and the amount you send is otherwise ignored. The rest key off a value you already send anyway, such as the billing ZIP or the CVV.

When you need an outcome no amount produces, send a control field instead. Control fields go on the transaction as a custom field, are matched without regard to case, and outrank the amount triggers. Every one of them is listed at the bottom of this page.

One constraint applies to the custom-field channel. If the merchant has defined any custom fields at all, every submitted custom-field name has to match one of those definitions, and a name that doesn't match is rejected with a 400. A sandbox merchant with no custom-field definitions accepts any name, which is the usual case. If you get a 400 naming the control field you sent, define a custom field with that name on the merchant.

Nothing on this page reaches a card network or moves money, and none of it works on a merchant routed to a live processor.

Test cards

Every card below is a published test number: it's issued to nobody, carries no funds and reaches no card network. Send one with the expiry and CVV shown. Any other network test card works too, as long as the BIN database knows its prefix.

One card per brand

These cards decide nothing about the outcome; the amount does that. Send each brand at least once, because several response modifiers are brand-scoped and a client that only ever sends one brand has never exercised its own brand handling.

Cards that classify as something specific

Send one of these when you need the platform to see a debit, prepaid, commercial, government, healthcare or EBT card. The full number resolves to the classification shown, in every environment, so acceptance rules, fee and surcharge eligibility, enhanced-data requirements and the commercial-card indicator on the response all behave as they would for a real card of that kind. Only the exact number classifies this way; a number that merely shares the prefix resolves from the BIN database like any other.

The amount still decides the outcome for these cards, with one exception: the EBT card takes no amount trigger and approves unless a control field says otherwise. To see a debit routing indicator on the response, send isDebitRouting as true on the card; the loopback.routing control field outranks it.

For one scenario per classification card, with the request to send, the classification to expect on the response and the behavior each card lets you observe, read Sandbox test cards.

Start here: one guaranteed case each way

If you only wire up two tests per flow, wire up these. Each pair is guaranteed to succeed and to fail respectively, and neither depends on anything about the card you send.

Card authorization

The cents of the transaction amount select the outcome. These apply to Visa, Mastercard, Amex and Discover; a brand the sandbox does not recognise approves everything.

Partial approval and prepaid

Send a prepaid indicator of P (or a partial-authorization indicator of true) and the exact amount selects the outcome. This is how you exercise a partial approval, which is the case most integrations get wrong.

Prepaid balance responses

Send a prepaid indicator of B and the exact amount selects which balances come back, including negative ones.

ACH debits and returns

A transaction carrying check data runs on the ACH rail, where the cents of the amount select the NACHA return. An ACH return is reported as a decline with the return code and reason on the response. That decline is synchronous and final: the sale was refused, so no settlement status ever moves and no ACH lifecycle event is published. The ordinary decline notification still fires. Use this flow to prove your code reads a return code off a declined response. To exercise an ACH webhook, send a sale at an approving amount and then move it with the sandbox ACH status endpoint, which publishes the real status-changed and returned events on demand. The VeriCheck sandbox remains the way to see the real multi-day timing alongside them.

Processor failover

The sandbox can report that it did not process a transaction at all, which is what makes the gateway attempt its one-shot authorization failover. Nothing is charged either way.

Address verification (AVS)

The billing ZIP selects the AVS response code. The code comes back on the transaction whatever your own AVS policy then does with it.

Cardholder verification (CVV)

The CVV selects the cardholder-verification response code. Any CVV without a trigger of its own comes back as a mismatch, so an arbitrary value is a usable negative case.

Response modifiers

These amounts don't change whether a transaction approves. They change the shape of the response, which is what you want when you're testing your parser.

Response latency

Send loopback.latencyProfile with one of these names and the sandbox takes a realistic amount of time to answer. Each delay is sampled from a log-normal distribution fitted to the profile's median and 95th percentile, then capped at its 99th, so repeated calls vary the way a real processor does rather than pausing for a fixed interval.

Send loopback.latencyMs instead when you want an exact delay, or custom as the profile name together with the three percentile fields to fit your own distribution.

Control fields

Every field the sandbox reads. Send either spelling, on a transaction custom field. A control field outranks the amount triggers above.

Reading back which trigger fired

Every transaction the sandbox answers comes back with a loopbackSimulation field: one entry for each trigger above that your request fired, and one for each response value the sandbox filled in from a default because nothing matched. Read it when an answer isn't the one you expected and you want to know which trigger the sandbox actually saw.

Entries carry isDefault, and the ones set to true are worth knowing about. A response can come back with an address or card verification result that none of your values asked for, which reads like a second deliberate failure beside the case you meant to test. The flag tells the two apart: false is a trigger you sent, true is a value the sandbox supplied.

Each entry says what the sandbox matched on, the value it matched, and what it did as a result. A card verification entry reports the response code the sandbox returned and never the security code you sent, so nothing you submit on a card comes back in this field.

The field describes a simulation, so it's only on transactions the sandbox answered. Anything a live processor handled returns null for it. Nothing in it changes what the transaction did: the ordinary response fields stay the authority on the outcome, and this explains how the sandbox arrived at them.

3-D Secure outcomes

The cents of the amount also decide how the card issuer answers 3-D Secure authentication, so you can test a challenge, a declined authentication, or an issuer that can't answer from your own test run. Send an amount ending in the cents shown below. Any other amount gets the sandbox's default outcome.

These outcomes apply to a keyed card payment on the hosted payment page, or through the embed SDK, for a sandbox merchant with 3-D Secure turned on. A sale sent straight to the API carries no 3-D Secure authentication, so the amount has no 3-D Secure effect there. The card authorization for these amounts is the default approval, so you can combine an outcome with any test card.

Only an authenticated or attempted result is attached to the transaction, and only those shift liability to the issuer. For any other result, your merchant's 3-D Secure policy decides whether the payment continues without authentication or is refused.

A challenge opens the card issuer's verification window on the payment page. The sandbox doesn't host an issuer page to complete the verification in, so the window stays open. Select Cancel to close it, and the payment continues the way your merchant's 3-D Secure policy treats an abandoned verification.

Forcing an API error

The triggers above force what a processor does. These force what the API does, which is the half your retry and backoff code is written against. Send the header with one of these values and the call is answered with that failure and nothing else happens: no transaction is saved, no processor is called, and no webhook is sent. The call is still recorded in your API request logs, so you can see exactly what you sent alongside the response you were given.

Send the value as the request header X-WinkPG-Mock-Error. The name in the first column is accepted, and so is the HTTP status on its own and, where the case has one, the error code it returns. Matching ignores case.

Only a test key can force an error. On a live key the header is ignored and the request is processed normally, and a value naming no case below is ignored the same way. Sending the header is never itself an error, so client code that always sets it behaves correctly in production.

The forced 429 carries the same X-RateLimit-Limit and X-RateLimit-Remaining headers the real limiter emits, and both it and the 503 carry Retry-After in whole seconds. Wait that long before you retry. That's the behavior these cases exist to let you prove.

Advancing time in the sandbox

The triggers above force what happens inside one request. These reach the behavior that only happens when time passes, which you would otherwise have to wait out. Each one brings a deadline your merchant already had forward to now, then runs the same evaluation the platform runs on its own schedule, so what comes out is what a scheduled run produces.

These controls are accelerators, not a test clock. Each one moves a single deadline and nothing else, so they don't add up into a simulated future: running billing early doesn't age anything else, and nothing here moves a date backwards or changes a record that already exists.

POST to the route with a test key and no body. The call answers once the work has been done, so whatever it produced is there to look at by the time you get the response. Both the key and the merchant have to be in the sandbox: a live key is refused, and so is a test key whose merchant has been promoted to production.

Everything an accelerator produces is real. The charges go through the payment path, the webhooks are sent to your endpoints, and the records appear in your logs and history exactly as they would have on the original schedule.