Skip to content

One account number per payment.

Create a transaction, show your customer the account number, and get paid the moment the transfer lands. Confirmed by webhook, polling or a live event, and settled to your bank.

Pay exactly

₦25,000.00

To account number

Bank
Partner Bank
Account name
ACME STORES / YUSR
Status
Waiting for transfer
Expires in
--:--

Transfer exactly this amount to the account above before it expires.

Follow one payment from the API call to your bank account: order-1042, for ₦25,000.00.

Step 1: Create a transaction

14:00:00₦25,000.00 requested

Your server sends the amount in kobo and your own reference. The response carries a one-time account number reserved for this payment, the fee quoted up front, and a link to a hosted payment page.

Amounts are integers from the request to the settlement.

Quick startAPI reference

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",
    "customer": { "name": "Ada Obi", "email": "ada@example.com" }
  }'
201 Created
{
  "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
  "object": "transaction",
  "status": "pending",
  "amount": 2500000,
  "fee": 37500,
  "net_amount": 2462500,
  "reference": "order-1042",
  "payment": {
    "account_number": "9912345678",
    "bank_name": "Partner Bank",
    "account_name": "ACME STORES / YUSR",
    "amount": 2500000,
    "expires_at": "2026-10-06T14:30:00.000Z"
  },
  "checkout_url": "https://pay.yusr.ng/pay_Zk3xV9qLm2Rt7YwB4nHs8dJc6uPa1eGf",
  …
}

Step 2: Your customer transfers

14:06:40₦25,000.00 sent

They pay from any Nigerian bank app: ten digits and an exact amount. The account name carries your business name, so they recognise who they are paying.

  • In your own checkout

    Show the four fields from payment: account number, bank, account name and amount.

  • Or send a link

    Every transaction has a checkout_url. It opens a hosted page with the same details, a countdown and the live status, under your name, logo and brand colour.

See every state of the hosted page

Address: pay.yusr.ng/pay_Zk3xV9qLm2Rt7YwB4nHs8dJc6uPa1eGf

Acme Stores

Pay exactly

₦25,000.00

To account number

Bank
Partner Bank
Account name
ACME STORES / YUSR
Status
Waiting for transfer
Expires in
--:--
Reference
order-1042

Transfer exactly this amount to the account above before it expires.

Step 3: The payment is confirmed

14:07:12₦25,000.00 received

The transfer is matched to the transaction by its account number, with no narration to read. You hear about it three ways, and all three carry the same transaction object.

Use the webhook to fulfil the order, the live event to update the page your customer is looking at, and polling as the fallback.

transaction.paid
POST /webhooks/yusr
X-Yusr-Event-Type: transaction.paid
X-Yusr-Timestamp: 1791295632
X-Yusr-Signature: v1=dc0334c8b6bb54fe…

{
  "id": "evt_01JA9QB2V8K1M3N5P7Q9R2S4T6",
  "type": "transaction.paid",
  "created_at": "2026-10-06T14:07:12.000Z",
  "mode": "live",
  "data": {
    "transaction": {
      "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
      "status": "paid",
      "amount": 2500000,
      "amount_received": 2500000,
      "fee": 37500,
      "net_amount": 2462500,
      "reference": "order-1042",
      "paid_at": "2026-10-06T14:07:12.000Z",
      …
    }
  }
}
Comparison of the webhook, polling and realtime confirmation channels
WebhookPollingRealtime
Use it forFulfilmentA fallbackThe checkout page
How it arrivesSigned POST to your serverGET the transaction by id or referenceEvent on a socket
DeliveryAt least once, retried for 22 hoursOn requestOn every change
Authenticates withWebhook secretSecret keyShort-lived client token

Step 4: Your money is settled

T+0 or T+1₦24,625.00 to your bank

The fee comes off as the payment is booked and the rest is credited to your balance. Settlement pays that balance to your verified bank account on the schedule agreed when you go live.

Each settlement lists the transactions in it, with gross, fee and net, in the dashboard, as CSV and by API.

Received for order-1042
₦25,000.00
Fee, 1.5% capped at ₦2,000.00
−₦375.00
Settled to your bank
₦24,625.00

A worked example on the published plan.

1.5%capped at ₦2,000.00 per successful transfer.

No setup fee, no monthly fee, nothing for expired or cancelled transactions. From ₦133,333.34 upwards every transfer costs the capped amount.

Worked examples and pricing questions

Fee calculator

The amount you want to collect for one payment.

Fee1.5% of the amount
₦375.00
Customer transfers
₦25,000.00
You receive
₦24,625.00

Fee ₦375.00. Customer transfers ₦25,000.00. You receive ₦24,625.00.

Adds the fee to what your customer transfers so you receive the full amount. Set per account.

Plan: 1.5% capped at ₦2,000.00 (1.5% of the amount, never more than ₦2,000.00). Fees are calculated in kobo and rounded to the nearest kobo.

Built so the money arrives

Current availability is on the status page.

  • Signed webhooks

    Every delivery is signed with HMAC-SHA256 over a timestamp and the raw body. Replays older than five minutes are rejected.

  • Idempotency keys

    Retry a create call with the same Idempotency-Key and you get the original response back. A network blip never makes two accounts.

  • Two-factor sign-in

    Owners and Admins must use two-factor authentication. Secret keys are shown once and stored only as hashes; live keys take IP allowlists.

  • Encrypted verification files

    Business verification documents and sensitive personal fields are encrypted at rest. Traffic is encrypted in transit with TLS.

  • Append-only ledger

    Every payment is booked in a double-entry ledger that is reconciled daily. Nothing is lost, counted twice or settled twice.

  • Audit log

    Key rolls, webhook changes, settings and team changes are written to an audit log you can read in the dashboard.

Start in the sandbox today

Test keys are issued the moment you sign up. Simulate paid, underpaid, overpaid, late and expired transfers, then go live once your business is verified.