Supported sandbox payment API

Use https://api.sandbox.<White Label domain> with a test key and the existing request signing scheme. Your operator must enable a simulator-capable release first. Objects carry livemode: false and environment: "sandbox".

Current simulator scope

Test balances, API-driven payment outcomes and signed callbacks to configured test endpoints are supported. QR, checkout and slip intake are unavailable. Passing these tests does not establish live-payment readiness. The 100.00–116.00 table in the sandbox design is an advanced target, not this execution profile's verified scenario catalog.

First test

1. Create a test API key from API Keys in an authoritative test Merchant session. Select the necessary deposits:read/write, withdrawals:read/write, wallet:read and sandbox:write scopes. Only sandbox:write is Test-only. Live payment and wallet grants follow the Live P2P profile.
2. Call POST /v1/pay/sandbox/topups with {"amount_minor":10000000,"currency":"THB"} and an Idempotency-Key.
3. Create a transaction using POST /v1/pay/deposits or POST /v1/pay/withdrawals, retaining our field names, signatures and integer minor units.
4. Read GET /v1/pay/balance, the transaction by ID and GET /v1/pay/events. Page events using since_sequence and limit.

Retries use a fresh nonce and signature but the original mutation body and idempotency key. A changed body with the same key returns 409 idempotency_key_reused without another wallet effect or event.

Deterministic outcomes

Amount in THB	Deposit	Withdrawal
1,001–2,000	settled	settled
2,001–3,000	rejected	rejected
3,001–4,000	reversed	rejected
4,001–5,000	expired	expired
Other amounts, including above 5,000	awaiting_payment	open

Whole THB amounts from 1 to 10,000,000 per request are supported. Test fees are zero in this profile. Automatic outcomes are applied during creation without a delayed callback. A reversed deposit settles at version 1 then reverses at version 2 in the same transaction, recording opposite ledger entries and both events. Its final net wallet effect is zero.

Complete a pending deposit using POST /v1/pay/sandbox/deposits/{id}/simulate with {"outcome":"succeed"}, {"outcome":"fail"} or {"outcome":"expire"}. The matching withdrawal path accepts only succeed or fail. Both sandbox:write and the corresponding transaction write scope are required. Final transactions return 409 sandbox_transaction_not_pending.

Withdrawals reserve test funds on creation. Insufficient funds return 402 insufficient_balance; success consumes the reservation and failure releases it back into the available balance.

Test webhooks

Configure an endpoint in the Merchant test session before creating new events. The scheduler signs pinned canonical payload bytes with Ed25519 using the existing webhook verification scheme. Callbacks include X-Environment: sandbox, livemode: false and environment: "sandbox". Scheduler and signing keyring configuration are required; existing events are not backfilled. Deduplicate event IDs and compare transaction versions because delivery may be duplicated or reordered. Failed delivery uses the existing 11-attempt retry schedule.

The Merchant test backoffice Sandbox Tools page can top up this same wallet and complete pending transactions using an employee session with sandbox_tools:write. No API key is entered into the page.

Callback history shows delivery status and bounded attempt details, with all, pending and failed filters. It exposes endpoint hostname/version without payloads or secrets. Manual resend is unavailable. Its cookie-authenticated read endpoint is GET /v1/bo/sandbox/tools/callbacks with sandbox_tools:read. Opaque cursors expire after 15 minutes and bind the employee, scope, filter and page size. The inventory cutoff stays fixed while delivery statuses remain current.

Limits

• Payment API and Tools share 60 requests per minute, including reads, and 500 new transaction/topup creations per UTC day per Merchant. Daily limits do not block reading or completing existing pending transactions.
• Lazy 30-day history and receipt cleanup. Pending reservations are retained until resolved; receipt replay is not guaranteed beyond retention.
• Customer persistence, editable fees, reset, manual webhook replay and advanced slip scenarios remain unavailable. Unsupported payment routes return SANDBOX_UNSUPPORTED.
• Always validate the response environment and separate test handlers from live money processing.