Skip to content
YusrDocs

Sandbox and testing#

Every account starts with a full sandbox: test keys, test webhooks, test realtime events and a test dashboard. Instead of real bank transfers, you use the simulator to play the customer. It credits the account exactly like a real transfer would, so your webhook handler, checkout page and reconciliation code run the same way they will in production.

Nothing you do in the sandbox moves real money, and sandbox data is completely separate from live data.

Sandbox at a glance#

Sandbox (test mode)Live mode
Keyssk_test_…, pk_test_…sk_live_…, pk_live_…
AvailableRight after sign-upAfter business verification
Bank on the accountYusr Test BankThe partner bank that issued the account, for example Partner Bank
Account numbersSimulated: they can't receive real transfersReal, one-time accounts
How payments happenThe simulator (API or dashboard)Customers transfer from their bank apps
Webhooks and realtimeSent exactly as in live modeSent
SettlementsTest batches on your schedule; no money is paid outPaid out to your bank account
Simulator endpointAvailable403 sandbox_only

Test and live data never mix. A test transaction can't be fetched with a live key (404 not_found), webhook endpoints are registered per mode, and every object has a mode field.

Simulate a payment#

POST /v1/sandbox/transactions/{id}/simulate makes the simulated customer act on a test transaction. It returns the updated transaction once the payment has been processed, and fires the same webhooks and realtime events as a real transfer.

curl https://api.yusr.ng/v1/sandbox/transactions/txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y/simulate \
  -H "Authorization: Bearer $YUSR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "underpaid", "amount": 1000000, "payer_name": "Chinedu Okafor" }'

Parameters#

ParameterRequiredDescription
outcomeYespaid, underpaid, overpaid, late or expired.
amountNoAmount the simulated customer transfers, in kobo. Defaults depend on the outcome (below). Ignored for expired.
payer_nameNoName shown as the sender in payments[].payer_name. Defaults to ADA OBI.

Outcomes#

OutcomeWhat the simulator doesDefault amountResulting statusWebhooks
paidTransfers the amount still due.The remaining amount (the full payment.amount if nothing is outstanding)paidtransaction.paid
underpaidTransfers part of the amount.Half of the remaining amountunderpaidtransaction.underpaid
overpaidTransfers more than requested.The remaining amount plus 10% of payment.amount (at least ₦1)overpaidtransaction.overpaid
lateExpires a pending transaction, then transfers.The remaining amountlate_paymenttransaction.expired, then transaction.late_payment
expiredExpires a pending transaction without a payment.—expiredtransaction.expired

When you pass amount, the status is calculated from the money actually received, exactly as in live mode. For example, {"outcome": "overpaid", "amount": 1000} on a ₦25,000 transaction produces underpaid, because only ₦10 arrived. Use the outcome as the scenario you want and let the default amount do the rest, or pass an amount to test precise edge cases.

Simulate from the dashboard#

Open any test transaction in the dashboard and use Simulate payment to pick an outcome and an optional amount. This is handy for support teams and for demos, and produces the same events as the API.

Test scenarios#

Run these before you go live. Each one should leave your system in a correct, explainable state.

ScenarioHow to testWhat your integration should do
Happy pathCreate a transaction, simulate paid.Fulfil the order exactly once, even if the webhook arrives twice.
UnderpaymentSimulate underpaid.Show the outstanding amount and keep the order open until expiry.
Top-upSimulate underpaid, then paid.Two entries in payments; fulfil on transaction.paid.
OverpaymentSimulate overpaid.Fulfil, and follow your overpayment setting for the excess.
Second transfer after paymentSimulate paid twice.The status moves to overpaid; don't fulfil twice.
Abandoned checkoutSimulate expired.Release reserved stock; the checkout offers a new transaction.
Late paymentSimulate late.Flag the order for review; don't silently ship or drop it.
Payment after cancellationCancel a pending transaction, then simulate paid.Handle transaction.late_payment for a cancelled order.
Duplicate referenceCreate two transactions with the same reference.Handle 409 duplicate_reference and reuse the existing transaction.
Retry after a timeoutSend the same create request twice with one Idempotency-Key.Get one transaction; the second response has Idempotent-Replayed: true.
Webhook outageMake your endpoint return 500, simulate paid, then fix it.Recover through automatic retries or a resend, without double-processing.
Invalid signatureSend a request to your endpoint with a wrong X-Yusr-Signature.Respond 400 and do nothing else.

Simulator errors#

StatusCodeCause
400invalid_requestoutcome is missing or not one of the five outcomes, or amount isn't a positive integer.
403sandbox_onlyYou called the simulator with a live key.
404not_foundNo test transaction with this ID for your account.
409invalid_stateThe outcome isn't possible from the current status, for example expired on a transaction that isn't pending: "Only pending transactions can be expired (this one is expired)."

Moving to live#

When your tests pass, switch the key and the webhook secret, and nothing else:

  1. Complete business verification in the dashboard. Live keys work after approval.
  2. Replace sk_test_… with sk_live_… in your production configuration.
  3. Register your production webhook endpoint in live mode (HTTPS required) and use its new signing secret.
  4. Remove any calls to the simulator from production code paths.

The going-live checklist covers the rest.