Transactions#
A transaction is one request for payment. When you create it, Yusr issues a one-time bank account number that belongs to that transaction alone. Your customer transfers the exact amount to it from any Nigerian bank app, and Yusr matches the money to the transaction automatically: no narration codes, no manual reconciliation.
Create a transaction#
Request parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | integer | Yes | Amount in kobo, greater than zero. ₦25,000.00 is 2500000. Must be within your account's minimum and maximum. |
currency | string | No | Always NGN (the default). |
reference | string | Yes | Your unique reference, up to 100 characters: letters, digits and . _ - : /. |
description | string | No | Up to 200 characters, shown in your dashboard. |
customer.name | string | Yes | Payer's name, 1–100 characters. |
customer.email | string | Yes | Payer's email address. |
customer.phone | string | No | 7–15 digits with an optional leading +, for example +2348012345678. |
expires_in | integer | No | Seconds until the account expires, from 600 (10 minutes) to 259200 (72 hours). Default 1800 (30 minutes). |
metadata | object | No | Up to 20 keys of your own data (see Metadata). |
Unknown parameters are rejected with 400 invalid_request, so a typo never passes silently.
The transaction object#
| Field | Description |
|---|---|
id | Yusr transaction ID, prefixed txn_. |
mode | test or live, decided by the key that created it. |
status | Current status (see Statuses). |
amount | The amount you asked for, in kobo. |
amount_received | Sum of every transfer received so far, in kobo. |
fee | Yusr's fee in kobo, based on your fee plan and the amount received. |
fee_bearer | merchant (fee deducted from your settlement) or customer (fee added to what the payer sends). |
net_amount | What settles to you after fees, in kobo. |
payment.account_number | The one-time account number the payer transfers to. |
payment.bank_name | The bank that holds the account. The payer picks it in their bank app. |
payment.account_name | Your business display name, which the payer sees when they enter the account number. |
payment.amount | The exact amount the payer must transfer, in kobo. Includes the fee when fee_bearer is customer. |
payment.expires_at | When the account stops accepting the payment (ISO 8601, UTC). Same as expires_at. |
flags | overpaid, underpaid and late booleans, for quick filtering. |
payments | Each transfer received: id, amount, payer_name, payer_bank, payer_account_number (masked), received_at. |
paid_at | When the transaction was first fully paid, otherwise null. |
Amounts are in kobo#
Every amount in the API, in requests, responses and webhooks, is an integer number of kobo. ₦1.00 is 100,
₦2,500.50 is 250050. Decimals are rejected:
Convert user input with exact decimal arithmetic, never with floating point. The libraries include helpers:
toKobo('₦2,500.50') in Node.js and Money::toKobo('2,500.50') in PHP both return 250050.
Your account has a minimum and maximum amount per transaction. Amounts outside the range fail with
422 amount_out_of_range, and amounts that would push you past a daily or monthly volume cap fail with
422 limit_exceeded.
Statuses#
| From | To | When |
|---|---|---|
| pending | paid | The exact amount arrives before expires_at. |
| pending | underpaid | Less than the requested amount arrives before expires_at. |
| pending | overpaid | More than the requested amount arrives. |
| underpaid | paid | A top-up transfer completes the amount before expiry. |
| underpaid or paid | overpaid | Further transfers take the total above the requested amount. |
| pending | expired | Nothing arrives before expires_at. |
| pending | cancelled | You cancel the transaction while it is pending. |
| pending | failed | The account could not be issued at creation. |
| expired or cancelled | late_payment | Money arrives after the account expired or was cancelled. |
| paid, overpaid, underpaid or late_payment | reversed | Everything received is returned: a full refund under your payment settings, or a bank reversal. |
| Status | Final? | Meaning | What to do |
|---|---|---|---|
pending | No | Waiting for the transfer. | Show the account details. |
paid | Usually | The exact amount arrived before expiry. | Fulfil the order. |
underpaid | No, until expiry | Less than the full amount arrived. The account keeps accepting top-ups until expires_at. | Ask the payer to send the difference, or wait for expiry. |
overpaid | Yes | More than the requested amount arrived. | Fulfil the order. The excess is handled by your overpayment setting. |
expired | No | Nothing arrived before expires_at. | Release stock or ask the customer to start again. |
late_payment | Yes | Money arrived after the transaction expired or was cancelled. | Decide whether to fulfil. Your late-payment setting decides what happens to the money. |
cancelled | No | You cancelled it while it was pending. | Nothing. A transfer that still arrives becomes late_payment. |
failed | Yes | The account could not be issued. | Create a new transaction (with a new reference). |
reversed | Yes | Everything received was returned to the payer. | Reverse fulfilment if you already delivered. |
Every status change after creation sends a webhook and a realtime event with the
matching type, for example transaction.paid or transaction.late_payment.
Expiry#
Each account accepts the payment for a limited time: expires_in seconds after creation, between 10 minutes and
72 hours (30 minutes by default). Pick a window that matches how your customers pay:
| Use case | Suggested expires_in |
|---|---|
| Online checkout, customer pays right away | 1800 (30 minutes) |
| Invoice sent by email or WhatsApp | 86400 (24 hours) |
| School fees, B2B invoices | up to 259200 (72 hours) |
Values outside the range fail with 400 invalid_request, for example
expires_in must be at least 600 seconds (10 minutes).
When the time is up, a pending transaction becomes expired and you receive transaction.expired. An
underpaid transaction keeps its status and its partial payment is accepted or refunded according to your
underpayment setting.
Underpayments, overpayments and late payments#
Bank transfers are typed by hand, so customers sometimes send the wrong amount or pay too late. Yusr never
silently drops money: every transfer is recorded in payments, and amount_received holds the total.
| Situation | Status | Flag | Your setting decides |
|---|---|---|---|
Less than payment.amount before expiry | underpaid | flags.underpaid | At expiry: accept the partial payment, or refund it to the payer's account. |
More than payment.amount | overpaid | flags.overpaid | Accept the excess, or refund the excess to the payer. |
| Money after expiry or cancellation | late_payment | flags.late | Accept it, or refund it in full to the payer. |
Configure these in the dashboard under Settings → Payment behaviour. A full refund moves the transaction to
reversed.
Multiple transfers#
A payer can split a payment across several transfers, or top up after underpaying. Each transfer is a separate
entry in payments, and the status is recalculated from the total:
The first transfer sent transaction.underpaid; the second sent transaction.paid. The fee is calculated on
the amount actually received.
Idempotency#
Networks fail. If a create request times out, you can't know whether Yusr received it. Send an
Idempotency-Key header and retry with the same key and the same body: you get the original response back
(with the header Idempotent-Replayed: true) instead of a second account number.
- Keys are up to 255 characters and are remembered for 24 hours per mode.
- Derive the key from your own data, such as
checkout-<order id>-<attempt>, so it survives process restarts. - The body must match byte for byte. Serialise it once and resend the same bytes.
- Reusing a key with a different body fails with
409 idempotency_conflict. - If the first request is still running, the retry fails with
409 idempotency_in_progressandRetry-After: 1. 429and5xxresponses are not stored, so you can retry them with the same key.
The Node.js and PHP libraries send an idempotency key on every create, generating one when you don't, and reuse
it across their automatic retries. Idempotency keys work on every POST endpoint.
Unique references#
reference is unique per account and mode. Creating a second transaction with a reference you already used
fails with 409 duplicate_reference, and the response includes the existing transaction, so you can
recover without another lookup:
The transaction field holds the complete transaction object (shortened here).
Retrieve a transaction#
This endpoint is limited to one request per second per transaction. To wait for a payment, use webhooks or realtime, and poll only as a fallback.
List and search transactions#
GET /v1/transactions returns your transactions, newest first, with cursor pagination.
| Query parameter | Description |
|---|---|
reference | Only the transaction with this reference. |
status | One of the statuses. |
from, to | ISO 8601 date-times with an offset, for example 2026-10-01T00:00:00+01:00. Filter on created_at. |
limit | Page size, 1 to 100. Default 20. |
starting_after | Cursor: the next_cursor from the previous page. |
Cancel a transaction#
Cancel a transaction you no longer want paid, for example when the customer empties their cart. Only pending
transactions can be cancelled; anything else fails with 409 invalid_state. A transfer that still arrives
after cancellation is recorded as a late_payment, so the money is never lost.
Metadata#
Attach your own data to a transaction with metadata. It comes back on the transaction and in every webhook,
which makes it handy for linking a payment to your systems.
- Up to 20 keys, each up to 40 characters.
- Values are strings (up to 500 characters), numbers, booleans or
null. Nested objects are not allowed. - Don't store sensitive data such as card numbers, passwords or government ID numbers in metadata.
Account names and banks#
The payer sees payment.account_name in their bank app when they enter the account number. It carries your
business display name (for example ACME STORES / YUSR), so customers know who they are paying. Change
it in the dashboard under Settings → Business profile.
payment.bank_name is the bank that holds the account, which the payer must select in their app. It can differ
between transactions, so always show the value from the response rather than a hard-coded bank.