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 | |
|---|---|---|
| Keys | sk_test_…, pk_test_… | sk_live_…, pk_live_… |
| Available | Right after sign-up | After business verification |
| Bank on the account | Yusr Test Bank | The partner bank that issued the account, for example Partner Bank |
| Account numbers | Simulated: they can't receive real transfers | Real, one-time accounts |
| How payments happen | The simulator (API or dashboard) | Customers transfer from their bank apps |
| Webhooks and realtime | Sent exactly as in live mode | Sent |
| Settlements | Test batches on your schedule; no money is paid out | Paid out to your bank account |
| Simulator endpoint | Available | 403 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.
Parameters#
| Parameter | Required | Description |
|---|---|---|
outcome | Yes | paid, underpaid, overpaid, late or expired. |
amount | No | Amount the simulated customer transfers, in kobo. Defaults depend on the outcome (below). Ignored for expired. |
payer_name | No | Name shown as the sender in payments[].payer_name. Defaults to ADA OBI. |
Outcomes#
| Outcome | What the simulator does | Default amount | Resulting status | Webhooks |
|---|---|---|---|---|
paid | Transfers the amount still due. | The remaining amount (the full payment.amount if nothing is outstanding) | paid | transaction.paid |
underpaid | Transfers part of the amount. | Half of the remaining amount | underpaid | transaction.underpaid |
overpaid | Transfers more than requested. | The remaining amount plus 10% of payment.amount (at least ₦1) | overpaid | transaction.overpaid |
late | Expires a pending transaction, then transfers. | The remaining amount | late_payment | transaction.expired, then transaction.late_payment |
expired | Expires a pending transaction without a payment. | — | expired | transaction.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.
| Scenario | How to test | What your integration should do |
|---|---|---|
| Happy path | Create a transaction, simulate paid. | Fulfil the order exactly once, even if the webhook arrives twice. |
| Underpayment | Simulate underpaid. | Show the outstanding amount and keep the order open until expiry. |
| Top-up | Simulate underpaid, then paid. | Two entries in payments; fulfil on transaction.paid. |
| Overpayment | Simulate overpaid. | Fulfil, and follow your overpayment setting for the excess. |
| Second transfer after payment | Simulate paid twice. | The status moves to overpaid; don't fulfil twice. |
| Abandoned checkout | Simulate expired. | Release reserved stock; the checkout offers a new transaction. |
| Late payment | Simulate late. | Flag the order for review; don't silently ship or drop it. |
| Payment after cancellation | Cancel a pending transaction, then simulate paid. | Handle transaction.late_payment for a cancelled order. |
| Duplicate reference | Create two transactions with the same reference. | Handle 409 duplicate_reference and reuse the existing transaction. |
| Retry after a timeout | Send the same create request twice with one Idempotency-Key. | Get one transaction; the second response has Idempotent-Replayed: true. |
| Webhook outage | Make your endpoint return 500, simulate paid, then fix it. | Recover through automatic retries or a resend, without double-processing. |
| Invalid signature | Send a request to your endpoint with a wrong X-Yusr-Signature. | Respond 400 and do nothing else. |
Simulator errors#
| Status | Code | Cause |
|---|---|---|
| 400 | invalid_request | outcome is missing or not one of the five outcomes, or amount isn't a positive integer. |
| 403 | sandbox_only | You called the simulator with a live key. |
| 404 | not_found | No test transaction with this ID for your account. |
| 409 | invalid_state | The 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:
- Complete business verification in the dashboard. Live keys work after approval.
- Replace
sk_test_…withsk_live_…in your production configuration. - Register your production webhook endpoint in live mode (HTTPS required) and use its new signing secret.
- Remove any calls to the simulator from production code paths.
The going-live checklist covers the rest.