Changelog#
Changes to the Yusr API, libraries and dashboard, newest first.
v1.0.0 — 6 October 2026#
The first release of the Yusr API (/v1).
Payments#
- Transactions with dynamic virtual accounts.
POST /v1/transactionsissues a one-time account number for each payment, with the exact amount to transfer and an expiry between 10 minutes and 72 hours (30 minutes by default). Amounts are integers in kobo. - Full payment lifecycle. Statuses
pending,paid,underpaid,overpaid,expired,late_payment,reversed,failedandcancelled, with multiple transfers to one account summed intoamount_received. - Idempotency. An
Idempotency-Keyheader on anyPOSTreplays the original response for 24 hours. - Duplicate reference protection. References are unique per account and mode; reusing one returns
409 duplicate_referencewith the existing transaction. - Retrieve, list and cancel.
GET /v1/transactions/{id}for polling,GET /v1/transactionswith filters and cursor pagination, andPOST /v1/transactions/{id}/cancelwhile pending.
Notifications#
- Signed webhooks. HMAC-SHA256 signatures over the timestamp and raw body, a 5-minute replay window, retries with backoff for about 22 hours, test events and manual resends.
- Webhook endpoints API. Create, update, delete, test and roll the signing secret of endpoints with
/v1/webhooks. - Events API.
GET /v1/eventsandGET /v1/events/{id}, andPOST /v1/events/{id}/resend. - Realtime. Socket.IO at
/v1/realtimewith the same payloads as webhooks, the current state on every subscribe, and browser client tokens fromPOST /v1/transactions/{id}/client-token.
Money#
- Settlements and balance.
GET /v1/balance,GET /v1/settlementsandGET /v1/settlements/{id}with the transactions in each batch, plus thesettlement.completedevent. - Banks.
GET /v1/bankslists Nigerian banks and their codes.
Testing#
- Sandbox simulator.
POST /v1/sandbox/transactions/{id}/simulatewith the outcomespaid,underpaid,overpaid,lateandexpired, firing the same webhooks and realtime events as real transfers.
Libraries and tools#
@yusr/nodefor Node.js 18+: typed resources, automatic idempotency keys and retries, webhook verification, auto-pagination and a polling helper.yusr/yusr-phpfor PHP 8.1+, with the same features and a Laravel example.@yusr/jsfor the browser:subscribeToTransactionand the accessiblerenderPaymentWidget.- OpenAPI 3.1 document at
GET /v1/openapi.json, which also powers the API reference. - Dashboard with test and live modes, transactions, settlements, API keys, webhook delivery logs, request logs, team roles and business verification.
- Documentation with guides, samples in cURL, Node.js, PHP and Python, and the API reference.
Versioning policy#
The API version is part of the URL: every endpoint lives under /v1.
Additive changes ship without a new version. We may add new endpoints, new optional request parameters, new fields in responses and webhook payloads, new event types, new error codes and new enum values (such as a new transaction status). Build tolerant readers:
- Ignore fields you do not recognise instead of rejecting the response.
- Handle unknown event types by acknowledging them with
2xxand ignoring them. - Treat unknown statuses and error codes as a safe default, for example "not paid yet" or "do not retry".
- Do not depend on the order of keys in JSON objects.
Breaking changes ship under a new version. Removing or renaming a field, changing a type or changing
behaviour you rely on would happen only in a new API version (for example /v2), announced in advance on this page,
with time to migrate while /v1 keeps working.
SDK releases follow semantic versioning: breaking changes to a library's interface come with a new major version.