Checkout sandbox scenarios

Use this when you integrate hosted checkout with a sandbox API key and the sandbox base URL (same host as production, with a /sandbox/api/ path prefix — see Organization & merchant).

There are two ways to exercise outcomes:

1. Scripted simulation (no real card) — when your deployment runs the internal simulation layer (internal test mode). You pass sandbox_simulate on POST /api/checkout/create/ (or POST /sandbox/api/checkout/create/) and complete the usual create → hosted page → create-nd8-payment → sync-status flow; the next GET payment–equivalent step returns a fixed provider status for that session.
2. Provider sandbox — when the platform uses sandbox credentials, card behaviour is defined by the payment provider (test instruments, decline rules, etc.). Use the sandbox test instruments available in your environment; do not send sandbox_simulate unless your environment documents it as supported.

Optional field: sandbox_simulate

Property	Value
Where	JSON body of POST /api/checkout/create/ (or under /sandbox/api/)
Requires	Sandbox API key (environment: sandbox) + sandbox API base URL
Production keys	Field present → 400 Bad Request
Effect on payment	Scripted GET payment responses only when the server uses internal simulation (e.g. automated tests). With a live provider sandbox, the field may be stored on the session but does not change the provider’s real status—use the provider’s own test instruments.

When simulation is active, allowed values are exactly:

sandbox_simulate	Simulated provider outcome	Typical POST /api/checkout/sync-status/ status	Merchant wallet credited?
(omit field)	PAYMENT_SUCCESS + depositStatus: succeeded	SUCCESS	Yes (same as happy path)
payment_failed	PAYMENT_FAILED	FAILED	No
checkout_canceled	CHECKOUT_CANCELED	CANCELED	No
canceled	CANCELED	CANCELED	No
success_pending_deposit	PAYMENT_SUCCESS + depositStatus: pending	SUCCESS (transaction may show paid; deposit not settled)	No — waits for deposit before settlement rules apply
checkout_pending	CHECKOUT_PENDING	CHECKOUT_PENDING	No — keep polling sync until a terminal state

Mapping to “real world” checks

• Good card / paid — omit sandbox_simulate (or use the provider sandbox success path).
• Declined / insufficient / issuer error — use payment_failed in simulation, or the matching provider sandbox decline in live sandbox mode.
• Customer abandoned checkout — checkout_canceled or canceled.
• Authorized but not captured yet — success_pending_deposit.
• Still at provider checkout — checkout_pending (your client should keep calling sync until terminal).

Automated tests

Backend tests cover each scenario end-to-end:

cd backend && python manage.py test transactions.tests.test_checkout_sandbox_simulate -v 2

Related

• Create payment — request body including sandbox_simulate
• Organization & merchant — sandbox keys and webhook environment