Skip to content
YusrDocs

Yusr documentation#

Yusr gives every payment its own bank account number. Your customer transfers from any Nigerian bank app, and you are notified the moment the money lands — by signed webhook, by polling, or over a realtime socket. Funds are settled to your bank account automatically, with fees deducted at source.

How a payment works#

Create a transaction#

Your server calls POST /v1/transactions with the amount in kobo, your reference and the customer's details.

Show the account details#

The response includes a dedicated account number, the bank name (for example Partner Bank), the account name and the exact amount to transfer. Show these on your checkout page with a countdown to the expiry time.

Receive confirmation#

When the transfer arrives, Yusr sends a signed transaction.paid webhook. You can also poll GET /v1/transactions/{id} or subscribe to realtime updates.

Get settled#

The amount, minus the Yusr fee, is settled to your bank account on your T+0 or T+1 schedule.

The quick start walks through all four steps in the sandbox, in about ten minutes.

Make your first request#

All amounts are integers in kobo: ₦25,000.00 is 2500000. Use a test secret key (sk_test_…) from the dashboard while you build; test keys never move real money.

curl https://api.yusr.ng/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "reference": "order-1042",
    "description": "Order #1042",
    "customer": { "name": "Ada Obi", "email": "ada@example.com" },
    "metadata": { "cart_id": "c_88" }
  }'

The 201 Created response contains everything your customer needs to pay:

JSON
{
  "id": "txn_01M47EG1XHH9S3MTQD3FJ156FT",
  "object": "transaction",
  "mode": "test",
  "status": "pending",
  "amount": 2500000,
  "amount_received": 0,
  "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": "9951643289",
    "bank_name": "Yusr Test Bank",
    "account_name": "ACME STORES / YUSR",
    "amount": 2500000,
    "expires_at": "2026-10-06T02:20:49.778Z"
  },
  "flags": {
    "overpaid": false,
    "underpaid": false,
    "late": false
  },
  "payments": [],
  "metadata": {
    "cart_id": "c_88"
  },
  "created_at": "2026-10-06T01:50:49.786Z",
  "updated_at": "2026-10-06T01:50:49.786Z",
  "paid_at": null,
  "expires_at": "2026-10-06T02:20:49.778Z"
}

Show the customer payment.account_number, payment.bank_name, payment.account_name and payment.amount (the exact amount to transfer) until payment.expires_at. In test mode the bank is the simulated Yusr Test Bank; in live mode it is the partner bank that holds the account.

Guides#