API reference
Accept bank-transfer payments in Nigeria with dynamic virtual accounts. All amounts are integers in kobo (₦1 = 100 kobo). Authenticate with Authorization: Bearer sk_test_… or sk_live_….
- Version
- 1.0.0
- Base URL
- https://api.yusr.ng/v1
- Specification
- openapi.jsonOpenAPI 3.1
Base URL
All endpoints live under one base URL. Your secret key decides whether a request runs in test mode (sk_test_) or live mode (sk_live_) — there is no separate sandbox host.
Authentication
Send your secret key as a bearer token on every request. Keep it on your server: never ship it in a browser, a mobile app or a repository. Browsers use short-lived client tokens instead. See Authentication for rolling keys and IP allowlists.
Conventions
- Requests and responses are JSON (
Content-Type: application/json). Unknown request fields are rejected withinvalid_request. - Amounts are integers in kobo (₦1 = 100 kobo): ₦25,000.00 is
2500000. Currency is alwaysNGN. - Timestamps are ISO 8601 strings in UTC, e.g.
2026-10-06T14:30:00.000Z. - IDs carry a type prefix:
txn_,pay_,stl_,whk_,evt_,whd_,req_. - Every response carries an
X-Request-Idheader. Quote it when you contact support. - New fields and event types can be added without a version change. Ignore fields you do not recognise.
Pagination
List endpoints return a page of results, newest first. Pass limit (1–100, default 20) and, for the next page, starting_after set to the previous page's next_cursor. Stop when has_more is false.
Idempotency
Send an Idempotency-Key header (up to 255 characters) on POST requests. Retrying with the same key and the byte-identical body within 24 hours returns the original response with Idempotent-Replayed: true instead of performing the action twice. Reusing a key with a different body returns 409 idempotency_conflict. Responses with status 429 or 5xx are not stored, so you can safely retry them with the same key.
Errors
Errors use conventional HTTP status codes and a stable, machine-readable code. When a specific parameter caused the error, param names it. The error catalogue lists every code with its fix.
Rate limits
Each secret key can make 100 requests in a burst and 25 per second sustained; retrieving a single transaction is limited to one request per second per transaction. Over the limit you get 429 rate_limited with a Retry-After header. See Rate limits.
Endpoints
Transactions
A transaction issues a one-time account number for a single payment. Create one per checkout attempt, show the account details to your customer, then confirm the payment by webhook, realtime socket or polling.
| get | /v1/transactionsList transactions | List transactions |
| post | /v1/transactionsCreate a transaction | Create a transaction |
| get | /v1/transactions/{id}Retrieve a transaction | Retrieve a transaction |
| post | /v1/transactions/{id}/cancelCancel a pending transaction | Cancel a pending transaction |
| post | /v1/transactions/{id}/client-tokenCreate a browser client token | Create a browser client token |
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.
| post | /v1/sandbox/transactions/{id}/simulateSimulate a payment outcome (test mode only) | Simulate a payment outcome (test mode only) |
Settlements
A settlement is a batch payout of your net collections to your verified settlement bank account, on your T+0 or T+1 schedule.
| get | /v1/settlementsList settlements | List settlements |
| get | /v1/settlements/{id}Retrieve a settlement with its transactions | Retrieve a settlement with its transactions |
Balance
Your balance shows money collected but not yet available (pending), money ready for the next settlement (available) and the total paid out to your bank (settled). All amounts are in kobo.
| get | /v1/balanceRetrieve balances | Retrieve balances |
Webhook endpoints
Register HTTPS endpoints to receive signed event notifications. Each mode (test and live) has its own endpoints and signing secrets.
| get | /v1/webhooksList webhook endpoints | List webhook endpoints |
| post | /v1/webhooksCreate a webhook endpoint | Create a webhook endpoint |
| get | /v1/webhooks/{id}Retrieve a webhook endpoint | Retrieve a webhook endpoint |
| patch | /v1/webhooks/{id}Update a webhook endpoint | Update a webhook endpoint |
| DEL | /v1/webhooks/{id}Delete a webhook endpoint | Delete a webhook endpoint |
| post | /v1/webhooks/{id}/testSend a signed sample event | Send a signed sample event |
| post | /v1/webhooks/{id}/roll-secretRoll the signing secret | Roll the signing secret |
Events
Every notification Yusr sends is recorded as an event. Use the event log to audit deliveries, catch up after downtime, or redeliver an event to your endpoints.
| get | /v1/eventsList events | List events |
| get | /v1/events/{id}Retrieve an event | Retrieve an event |
| post | /v1/events/{id}/resendResend an event to your webhook endpoints | Resend an event to your webhook endpoints |
Webhook events
Yusr sends these events to your webhook endpoints and to realtime subscribers. Each delivery is signed with X-Yusr-Signature; respond with a 2xx status within 10 seconds.
| Event | Sent when |
|---|---|
transaction.paid | The exact amount (or a top-up completing it) was received before expiry. |
transaction.underpaid | Less than the requested amount was received. |
transaction.overpaid | More than the requested amount was received. |
transaction.expired | The account expired without a payment. |
transaction.late_payment | Money arrived after the transaction expired or was cancelled. |
transaction.reversed | A received payment was reversed. |
transaction.cancelled | You cancelled a pending transaction. |
settlement.completed | A settlement was paid out to your bank account. |