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.
The 201 Created response contains everything your customer needs to pay:
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#
Create your first sandbox transaction and receive a webhook in about ten minutes.
AuthenticationTest and live keys, rolling keys without downtime, and IP allowlists.
Sandbox and testingSimulate paid, underpaid, overpaid, late and expired payments.
TransactionsStatuses, expiry, under-, over- and late payments, idempotency and references.
Displaying payment detailsShow the account number, exact amount and countdown so customers pay right first time.
WebhooksEvent types, payloads, signature verification and retries.
RealtimeUpdate your checkout page instantly with client tokens and sockets.
PollingConfirm a payment on your server by reading the transaction.
Settlements and feesWhen and how you get paid, and what each transfer costs.
ErrorsEvery error code with its HTTP status, meaning and fix.
Rate limitsBurst and sustained limits, and how to back off on 429.
Team rolesGive your team access with the right permissions.
Going liveBusiness verification, live keys and the launch checklist.
SDKs and librariesOfficial libraries for Node.js, PHP and the browser.
API referenceEvery endpoint, parameter and response, with samples in four languages.
ChangelogWhat changed in the API, libraries and dashboard.