Sandbox scenarios
SET API and SET Merchant API · Staging · Live since 2026-11-09
Before going live, an integration has to handle the outcomes that rarely happen on a good day: a rejected verification, a request for information, a returned payment. In staging, one call puts any of your sandbox objects into one of these outcomes, with the same answers and events production would give. The sandbox of SET's provider cannot produce these on its own, so SET records them itself.
POST /v1/sandbox/scenarios { "name": "payout_returned", "object": "po_…" }Every answer and every event a scenario raises is labelled "Sandbox: simulated" and carries simulated: true. No money moves. In production the route answers 404.
Scenarios
name | object | What happens |
|---|---|---|
kyb_rejected | a customer | customer.updated with status: "rejected". GET /v1/customers/{id} reads rejected with rejectionReasons (send up to five in reasons), and creates for the customer answer 409 verification_incomplete. |
rfi_raised | a customer | rfi.created for a stand-in request for information (sim_rfi_…), listed by GET /v1/customers/{id}/rfis. Answering it with POST /v1/rfis/{id}/responses closes it; the answers are not kept. |
deposit_in_review_then_refunded | a virtual account, or a simulated deposit (sim_dep_…) | deposit.funds_received, deposit.in_review, deposit.refunded. Optional amount. |
cash_out_payment_returned | a Cash-Out Address, or a simulated payment (sim_drain_…) | cash_out_payment.funds_received, .payment_submitted, .payment_processed, .returned. |
payout_returned, payout_undeliverable | a sandbox payout | The payout moves forward to returned or undeliverable, with payout.<state> at each step. |
microdeposit | a virtual account | One or two amounts under a dollar (optional amounts), listed first by GET /v1/virtual_accounts/{id}/microdeposits. |
wallet_initiation_required | a custodial wallet | GET /v1/wallets/{id} reads initiationRequired: true; payouts and withdrawals from it answer 409 initiation_required. |
kyb_rejected, rfi_raised, microdeposit and wallet_initiation_required last until you send the same call with "clear": true. The others are one-off outcomes. The answer lists the events the scenario raised, in order.
Related
- Run a sandbox scenario: the call.
- Environments and sandbox: staging keys and the other simulation calls.