Skip to content
YusrDocs

API reference

Sandbox

With a test secret key you can simulate what the payer does: an exact, partial, excess or late transfer, or an expiry. Simulations fire the same webhooks and realtime events as real transfers.

Sandbox endpoints
post/v1/sandbox/transactions/{id}/simulateSimulate a payment outcome (test mode only)

Read the Sandbox guide for the concepts behind these endpoints.

Simulate a payment outcome (test mode only)

post/v1/sandbox/transactions/{id}/simulate

Path parameters

Path parameters
idstringrequired

Request bodyapplication/json

Request body attributes
outcomestringrequired

One of paid, underpaid, overpaid, late, expired

amountinteger

Amount the simulated payer transfers. Defaults depend on outcome.

> 0, ≤ 100000000000

payer_namestring

max length 100

curl -X POST "https://api.yusr.ng/v1/sandbox/transactions/txn_01JA9Q3K7M2VXR8D5N0B4C6E2F/simulate" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "paid"
}'

Responses

200Updated transaction
Show response attributes
Response attributes
idstringrequired

Yusr transaction ID, prefixed txn_.

objectstringrequired

always "transaction"

modestringrequired

One of test, live

statusstringrequired

One of pending, paid, underpaid, overpaid, expired, late_payment, reversed, failed, cancelled

amountintegerrequired

Amount requested, in kobo.

amount_receivedintegerrequired

Sum of all payments received, in kobo.

feeintegerrequired

Yusr fee in kobo.

fee_bearerstringrequired

One of merchant, customer

net_amountintegerrequired

Amount settled to you after fees, in kobo.

currencystringrequired

always "NGN"

referencestringrequired
descriptionstring | nullrequired
customerobjectrequired
Show child attributes
namestringrequired
emailstringrequired
phonestring | nullrequired
paymentobjectrequired
Show child attributes
account_numberstringrequired
bank_namestringrequired
account_namestringrequired
amountintegerrequired

Exact amount the payer must transfer, in kobo.

expires_atstringrequired
flagsobjectrequired
Show child attributes
overpaidbooleanrequired
underpaidbooleanrequired
latebooleanrequired
paymentsarray of objectrequired
Show child attributes
idstringrequired
amountintegerrequired
payer_namestring | nullrequired
payer_bankstring | nullrequired
payer_account_numberstring | nullrequired

Masked, last 4 digits only.

received_atstringrequired
metadataobject of anyrequired
created_atstringrequired
updated_atstringrequired
paid_atstring | nullrequired
expires_atstringrequired
Response 200
{
  "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
  "object": "transaction",
  "mode": "test",
  "status": "paid",
  "amount": 2500000,
  "amount_received": 2500000,
  "fee": 37500,
  "fee_bearer": "merchant",
  "net_amount": 2462500,
  "currency": "NGN",
  "reference": "order-1042",
  "description": "Order #1042",
  "customer": {
    "name": "Ada Obi",
    "email": "ada@example.com",
    "phone": null
  },
  "payment": {
    "account_number": "9912345678",
    "bank_name": "Yusr Test Bank",
    "account_name": "ACME STORES / YUSR",
    "amount": 2500000,
    "expires_at": "2026-10-06T14:30:00.000Z"
  },
  "flags": {
    "overpaid": false,
    "underpaid": false,
    "late": false
  },
  "payments": [
    {
      "id": "pay_01JA9QB2T3W4X5Y6Z7A8B9C0D1",
      "amount": 2500000,
      "payer_name": "ADA OBI",
      "payer_bank": "Partner Bank",
      "payer_account_number": "******4321",
      "received_at": "2026-10-06T14:07:12.000Z"
    }
  ],
  "metadata": {
    "cart_id": "c_88"
  },
  "created_at": "2026-10-06T14:00:00.000Z",
  "updated_at": "2026-10-06T14:07:12.000Z",
  "paid_at": "2026-10-06T14:07:12.000Z",
  "expires_at": "2026-10-06T14:30:00.000Z"
}
Error responses
StatusMeaningError codes
400Invalid requestinvalid_request
401Authentication failedauthentication_failed
403Forbiddensandbox_onlymerchant_not_livemerchant_suspendedip_not_allowed
404Not foundnot_found
409Conflict (duplicate reference, idempotency conflict, invalid state)duplicate_referenceidempotency_conflictidempotency_in_progressinvalid_state
Try it in the sandbox