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.

How it works

  1. 1

    Create a transaction

    Your server sends the amount in kobo and your order reference. You get back a one-time account number reserved for this payment.

  2. 2

    Your customer transfers

    Show the account number, bank, account name and exact amount. They pay from any Nigerian bank app; the account name carries your business name.

  3. 3

    The payment is confirmed

    The moment the transfer lands you get a signed webhook or a live event, or you read the paid status when you poll.

  4. 4

    Your money is settled

    The fee comes off at source and your net amount settles to your verified bank account on a T+0 or T+1 schedule.

Three ways to know the money landed

All three carry the same transaction object. Use webhooks to fulfil orders, the live event to update the checkout page, and polling as a fallback.

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
transaction.paid
POST /webhooks/yusr
X-Yusr-Event-Id: evt_01JA9QB2V8K1M3N5P7Q9R2S4T6
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",
      …
    }
  }
}

One call to create a transaction

Send the amount in kobo, your reference and the customer. The response has everything your checkout needs to show: the account number, the bank, the account name and when it expires. Amounts are integers end to end.

Quick startAPI reference

import { Yusr } from '@yusr/node';

const prisma = new Yusr(process.env.YUSR_SECRET_KEY, {
  baseUrl: 'https://api.yusr.ng',
});

const txn = await prisma.transactions.create({
  amount: 2_500_000, // ₦25,000.00 in kobo
  reference: 'order-1042',
  customer: { name: 'Ada Obi', email: 'ada@example.com' },
});

// Show these to your customer
console.log(txn.payment);
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"
  },
  …
}

Fees

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

What a payment costs

The amount you want to collect for one payment.

Fee1.5%
₦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 money arrives

Payments are recorded in a double-entry ledger, every notification is signed, and every sensitive action leaves a trail.

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.