Skip to content
YusrDocs

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.

curl https://api.yusr.ng/v1/balance \
  -H "Authorization: Bearer sk_test_..."

Conventions

  • Requests and responses are JSON (Content-Type: application/json). Unknown request fields are rejected with invalid_request.
  • Amounts are integers in kobo (₦1 = 100 kobo): ₦25,000.00 is 2500000. Currency is always NGN.
  • 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-Id header. 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.

List response
{
  "object": "list",
  "data": [ … ],
  "has_more": true,
  "next_cursor": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F"
}

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.

Error response
{
  "error": {
    "code": "invalid_request",
    "message": "amount must be an integer number of kobo",
    "param": "amount",
    "request_id": "req_01JA9QH3M5P7R9T1V3X5Z7B9D1"
  }
}

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.

Transactions endpoints
get/v1/transactionsList transactions
post/v1/transactionsCreate a transaction
get/v1/transactions/{id}Retrieve a transaction
post/v1/transactions/{id}/cancelCancel a pending transaction
post/v1/transactions/{id}/client-tokenCreate 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.

Sandbox endpoints
post/v1/sandbox/transactions/{id}/simulateSimulate 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.

Settlements endpoints
get/v1/settlementsList settlements
get/v1/settlements/{id}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.

Balance endpoints
get/v1/balanceRetrieve balances

Webhook endpoints

Register HTTPS endpoints to receive signed event notifications. Each mode (test and live) has its own endpoints and signing secrets.

Webhook endpoints endpoints
get/v1/webhooksList webhook endpoints
post/v1/webhooksCreate a webhook endpoint
get/v1/webhooks/{id}Retrieve a webhook endpoint
patch/v1/webhooks/{id}Update a webhook endpoint
DEL/v1/webhooks/{id}Delete a webhook endpoint
post/v1/webhooks/{id}/testSend a signed sample event
post/v1/webhooks/{id}/roll-secretRoll 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.

Events endpoints
get/v1/eventsList events
get/v1/events/{id}Retrieve an event
post/v1/events/{id}/resendResend an event to your webhook endpoints

Banks

The list of Nigerian banks and their codes, for settlement account setup.

Banks endpoints
get/v1/banksList Nigerian banks

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.

EventSent when
transaction.paidThe exact amount (or a top-up completing it) was received before expiry.
transaction.underpaidLess than the requested amount was received.
transaction.overpaidMore than the requested amount was received.
transaction.expiredThe account expired without a payment.
transaction.late_paymentMoney arrived after the transaction expired or was cancelled.
transaction.reversedA received payment was reversed.
transaction.cancelledYou cancelled a pending transaction.
settlement.completedA settlement was paid out to your bank account.