In WinkPG, the sandbox isn't a separate platform. It's a state your merchant is in. A sandbox merchant lives on the same instance as a live one, answers at the same API address, and is reached through the same developer account. What the state changes is where the merchant's transactions can go: a sandbox merchant reaches a simulator or a processor's test host, and never a live one. Going live changes that state on the same merchant, so the integration you build against the sandbox is the one you run in production.

Sandbox and production are states of a merchant

Every merchant is in one of four environments, and the environment decides where its transactions can go.

There's no second platform behind the sandbox. Your merchant ID, the API address you call, and the account you sign in to the developer portal with are the same before and after your merchant goes live.

What a sandbox merchant can reach

A sandbox merchant routes its transactions in one of two processor modes. Your provider sets the mode on your merchant; you can't change it from the API or the developer portal.

• Loopback sends every transaction to the sandbox simulator, which is built in to WinkPG. Nothing leaves the platform, and you choose the outcome: an amount, a card, or a control field provokes a specific approval, decline, error, or delay, the same way every time. The testing page lists every trigger the simulator honors, read from the simulator's own definitions.
• Processor Test sends transactions to your merchant's real processor profiles, at each processor's own test host. Use it when you're certifying against a specific processor. The outcome comes from that processor's test host, not from the simulator.

Neither mode reaches a live host. A sandbox merchant resolves only a processor's test endpoint, and routing never sends a merchant that isn't in the sandbox to the simulator.

Test keys and live keys

An API key is stamped with an environment when it's created, taken from the environment its merchant is in at that moment:

• A key created for a merchant in Production starts with sk_live_.
• A key created for a merchant in any other environment starts with sk_test_.

The stamp never changes. On every call, WinkPG compares the key's stamp with the environment its merchant is in right now, and refuses a key that no longer matches with KEY_ENVIRONMENT_MISMATCH. An sk_test_ key stops working the moment its merchant goes live, and an sk_live_ key stops working if its merchant leaves production. In both cases the fix is a new key, created after the change.

A merchant on a trial whose deadline has passed is refused with TRIAL_EXPIRED instead, whichever key it presents. A new key doesn't help there; the trial has to be extended.

Some endpoints exist only for the sandbox: the on-demand batch close, the ACH status advance, and the time controls on the testing page that run scheduled work early. Each one refuses an sk_live_ key, and each one acts only on the merchant your key belongs to.

What a sandbox call looks like

A sandbox request is a production request. The paths, request bodies, response bodies, error codes, and webhook payloads are the same, so code that works against the sandbox runs live with nothing changed but the key.

Two things are worth knowing when you read a sandbox response:

• A transaction the sandbox simulator answered carries a loopbackSimulation field. It lists each trigger your request fired and each response value the simulator filled in from a default. It's null on every transaction a processor answered, including one answered by a processor's test host. The testing page explains how to read it.
• No field on a transaction says whether it's a sandbox transaction or a live one. Your code knows which environment it's in from the key it holds, not from anything on the transaction.

Going live

Going live is called promotion: it moves your merchant from Sandbox to Production. Promotion is an action your provider takes. You can't promote a merchant yourself, from the developer portal or from the API. The go-live checklist in the developer portal shows what your provider sees about your integration, scored from what you've done in the sandbox. It informs their decision; it doesn't make it.

Before promotion, your provider takes the sandbox simulator off your merchant. A merchant can't be promoted while the simulator is still one of its active processors, so a live merchant routes only to real processor profiles.

Promotion changes the environment on the same merchant record. It doesn't create a new merchant, so nothing is moved or re-keyed.

What stays the same:

• Your merchant ID.
• Your developer account and its access to the merchant.
• Your webhook endpoints, with their settings unchanged.
• Your saved scenarios in the developer portal. The portal runs scenarios only against a sandbox merchant, so they stay saved but don't run against your live merchant.
• Your request log, for as long as your provider's retention setting keeps each entry.
• Your go-live checklist.

What ends:

• Every sk_test_ key stops authenticating the moment promotion lands. Create your sk_live_ keys after promotion, because any key created earlier carries the sandbox stamp.
• The sandbox simulator, which your provider removed before promoting.
• The sandbox-only endpoints, which refuse a live key.
• The trial, if your merchant had one. Its deadline is cleared, so a live merchant is never refused for a lapsed trial.

If your provider also runs a separate sandbox deployment

Some providers run a second, separate deployment of the platform for testing, alongside the one this guide describes. That deployment is a different instance: it has its own address, its own accounts, its own merchants, and its own API keys. Nothing carries across between the two. A merchant, key, webhook endpoint, or saved scenario created on one doesn't exist on the other, and promoting a merchant on one changes nothing on the other.

The environments, keys, and promotion described above apply within each deployment on its own. Your provider tells you which deployment to integrate against. If you aren't sure which one you're using, ask before you build, because nothing you set up on one moves to the other.

See also

• Quickstart: Direct API: take your first sandbox payment over the API.
• Getting started with the API: create a key, authenticate a call, and read every authentication refusal code.
• Sandbox test cards: one scenario per sandbox test card, with the classification to expect on the response.
• The testing page: every trigger the sandbox simulator honors, how to read back which one fired, and the time controls.