Skip to content
YusrDocs

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/transactions issues 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, failed and cancelled, with multiple transfers to one account summed into amount_received.
  • Idempotency. An Idempotency-Key header on any POST replays the original response for 24 hours.
  • Duplicate reference protection. References are unique per account and mode; reusing one returns 409 duplicate_reference with the existing transaction.
  • Retrieve, list and cancel. GET /v1/transactions/{id} for polling, GET /v1/transactions with filters and cursor pagination, and POST /v1/transactions/{id}/cancel while 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/events and GET /v1/events/{id}, and POST /v1/events/{id}/resend.
  • Realtime. Socket.IO at /v1/realtime with the same payloads as webhooks, the current state on every subscribe, and browser client tokens from POST /v1/transactions/{id}/client-token.

Money#

  • Settlements and balance. GET /v1/balance, GET /v1/settlements and GET /v1/settlements/{id} with the transactions in each batch, plus the settlement.completed event.
  • Banks. GET /v1/banks lists Nigerian banks and their codes.

Testing#

  • Sandbox simulator. POST /v1/sandbox/transactions/{id}/simulate with the outcomes paid, underpaid, overpaid, late and expired, firing the same webhooks and realtime events as real transfers.

Libraries and tools#

  • @yusr/node for Node.js 18+: typed resources, automatic idempotency keys and retries, webhook verification, auto-pagination and a polling helper.
  • yusr/yusr-php for PHP 8.1+, with the same features and a Laravel example.
  • @yusr/js for the browser: subscribeToTransaction and the accessible renderPaymentWidget.
  • 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 2xx and 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.