Skip to content
YusrDocs

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#

curl https://api.yusr.ng/v1/transactions \
  -H "Authorization: Bearer $YUSR_SECRET_KEY" \
  -H "Idempotency-Key: checkout-order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "reference": "order-1042",
    "description": "Order #1042",
    "customer": { "name": "Ada Obi", "email": "ada@example.com", "phone": "+2348012345678" },
    "expires_in": 1800,
    "metadata": { "cart_id": "c_88", "channel": "web" }
  }'

Request parameters#

ParameterTypeRequiredDescription
amountintegerYesAmount in kobo, greater than zero. ₦25,000.00 is 2500000. Must be within your account's minimum and maximum.
currencystringNoAlways NGN (the default).
referencestringYesYour unique reference, up to 100 characters: letters, digits and . _ - : /.
descriptionstringNoUp to 200 characters, shown in your dashboard.
customer.namestringYesPayer's name, 1–100 characters.
customer.emailstringYesPayer's email address.
customer.phonestringNo7–15 digits with an optional leading +, for example +2348012345678.
expires_inintegerNoSeconds until the account expires, from 600 (10 minutes) to 259200 (72 hours). Default 1800 (30 minutes).
metadataobjectNoUp 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#

JSON
{
  "id": "txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y",
  "object": "transaction",
  "mode": "live",
  "status": "pending",
  "amount": 2500000,
  "amount_received": 0,
  "fee": 37500,
  "fee_bearer": "merchant",
  "net_amount": 2462500,
  "currency": "NGN",
  "reference": "order-1042",
  "description": "Order #1042",
  "customer": { "name": "Ada Obi", "email": "ada@example.com", "phone": "+2348012345678" },
  "payment": {
    "account_number": "9912345678",
    "bank_name": "Partner Bank",
    "account_name": "ACME STORES / YUSR",
    "amount": 2500000,
    "expires_at": "2026-10-06T14:30:00.000Z"
  },
  "flags": { "overpaid": false, "underpaid": false, "late": false },
  "payments": [],
  "metadata": { "cart_id": "c_88", "channel": "web" },
  "created_at": "2026-10-06T14:00:00.000Z",
  "updated_at": "2026-10-06T14:00:00.000Z",
  "paid_at": null,
  "expires_at": "2026-10-06T14:30:00.000Z"
}
FieldDescription
idYusr transaction ID, prefixed txn_.
modetest or live, decided by the key that created it.
statusCurrent status (see Statuses).
amountThe amount you asked for, in kobo.
amount_receivedSum of every transfer received so far, in kobo.
feeYusr's fee in kobo, based on your fee plan and the amount received.
fee_bearermerchant (fee deducted from your settlement) or customer (fee added to what the payer sends).
net_amountWhat settles to you after fees, in kobo.
payment.account_numberThe one-time account number the payer transfers to.
payment.bank_nameThe bank that holds the account. The payer picks it in their bank app.
payment.account_nameYour business display name, which the payer sees when they enter the account number.
payment.amountThe exact amount the payer must transfer, in kobo. Includes the fee when fee_bearer is customer.
payment.expires_atWhen the account stops accepting the payment (ISO 8601, UTC). Same as expires_at.
flagsoverpaid, underpaid and late booleans, for quick filtering.
paymentsEach transfer received: id, amount, payer_name, payer_bank, payer_account_number (masked), received_at.
paid_atWhen 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:

JSON
{
  "error": {
    "code": "invalid_request",
    "message": "amount must be an integer number of kobo",
    "param": "amount",
    "request_id": "req_01M47EGDQD6EGHZBABXK1SJA1X"
  }
}

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#

Transaction status lifecycleA transaction starts as pending. It becomes paid, underpaid, overpaid, expired, cancelled or failed. An underpaid transaction becomes paid after a top-up. Expired or cancelled transactions that later receive money become late_payment. Paid or overpaid transactions can become reversed.CreatedOutcomeAfterwardstop-uprefund or reversaltransfer after expirypendingunderpaidpaidoverpaidexpiredcancelledfailedreversedlate_payment
Status transitions. Every change after creation emits a webhook and realtime event.
Transaction status transitions
FromToWhen
pendingpaidThe exact amount arrives before expires_at.
pendingunderpaidLess than the requested amount arrives before expires_at.
pendingoverpaidMore than the requested amount arrives.
underpaidpaidA top-up transfer completes the amount before expiry.
underpaid or paidoverpaidFurther transfers take the total above the requested amount.
pendingexpiredNothing arrives before expires_at.
pendingcancelledYou cancel the transaction while it is pending.
pendingfailedThe account could not be issued at creation.
expired or cancelledlate_paymentMoney arrives after the account expired or was cancelled.
paid, overpaid, underpaid or late_paymentreversedEverything received is returned: a full refund under your payment settings, or a bank reversal.
StatusFinal?MeaningWhat to do
pendingNoWaiting for the transfer.Show the account details.
paidUsuallyThe exact amount arrived before expiry.Fulfil the order.
underpaidNo, until expiryLess 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.
overpaidYesMore than the requested amount arrived.Fulfil the order. The excess is handled by your overpayment setting.
expiredNoNothing arrived before expires_at.Release stock or ask the customer to start again.
late_paymentYesMoney arrived after the transaction expired or was cancelled.Decide whether to fulfil. Your late-payment setting decides what happens to the money.
cancelledNoYou cancelled it while it was pending.Nothing. A transfer that still arrives becomes late_payment.
failedYesThe account could not be issued.Create a new transaction (with a new reference).
reversedYesEverything 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 caseSuggested expires_in
Online checkout, customer pays right away1800 (30 minutes)
Invoice sent by email or WhatsApp86400 (24 hours)
School fees, B2B invoicesup 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.

SituationStatusFlagYour setting decides
Less than payment.amount before expiryunderpaidflags.underpaidAt expiry: accept the partial payment, or refund it to the payer's account.
More than payment.amountoverpaidflags.overpaidAccept the excess, or refund the excess to the payer.
Money after expiry or cancellationlate_paymentflags.lateAccept 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:

JSON
{
  "status": "paid",
  "amount": 2500000,
  "amount_received": 2500000,
  "payments": [
    {
      "id": "pay_01JA9QB2T3W4X5Y6Z7A8B9C0D1",
      "amount": 1250000,
      "payer_name": "ADA OBI",
      "payer_bank": "Partner Bank",
      "payer_account_number": "******4321",
      "received_at": "2026-10-06T14:05:40.000Z"
    },
    {
      "id": "pay_01JA9QC7N2P4R6S8T0V2W4X6Y8",
      "amount": 1250000,
      "payer_name": "ADA OBI",
      "payer_bank": "Partner Bank",
      "payer_account_number": "******4321",
      "received_at": "2026-10-06T14:09:02.000Z"
    }
  ]
}

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_progress and Retry-After: 1.
  • 429 and 5xx responses are not stored, so you can retry them with the same key.
JSON
{
  "error": {
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": "Idempotency-Key",
    "request_id": "req_01M47EGDB6YF51590C99CZRQX4"
  }
}

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:

JSON
{
  "error": {
    "code": "duplicate_reference",
    "message": "A transaction with this reference already exists.",
    "param": "reference",
    "request_id": "req_01M47EGDJG6NSRHZ2DRGH1H8ZT"
  },
  "transaction": {
    "id": "txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y",
    "object": "transaction",
    "status": "pending",
    "reference": "order-1042"
  }
}

The transaction field holds the complete transaction object (shortened here).

# The existing transaction is in the "transaction" field of the 409 response.
curl -s https://api.yusr.ng/v1/transactions \
  -H "Authorization: Bearer $YUSR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "reference": "order-1042",
    "customer": { "name": "Ada Obi", "email": "ada@example.com" }
  }' | jq '.transaction.id'

Retrieve a transaction#

curl https://api.yusr.ng/v1/transactions/txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y \
  -H "Authorization: Bearer $YUSR_SECRET_KEY"

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 parameterDescription
referenceOnly the transaction with this reference.
statusOne of the statuses.
from, toISO 8601 date-times with an offset, for example 2026-10-01T00:00:00+01:00. Filter on created_at.
limitPage size, 1 to 100. Default 20.
starting_afterCursor: the next_cursor from the previous page.
curl -G https://api.yusr.ng/v1/transactions \
  -H "Authorization: Bearer $YUSR_SECRET_KEY" \
  --data-urlencode "status=paid" \
  --data-urlencode "from=2026-10-01T00:00:00+01:00" \
  --data-urlencode "limit=50"
JSON
{
  "object": "list",
  "data": [{ "id": "txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y", "object": "transaction", "status": "paid" }],
  "has_more": true,
  "next_cursor": "txn_01JA9PZ4D2F6H8K0M2N4Q6S8U0"
}

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.

curl -X POST https://api.yusr.ng/v1/transactions/txn_01JA9Q3K7M2V8X4N6P0R2T5W7Y/cancel \
  -H "Authorization: Bearer $YUSR_SECRET_KEY"
JSON
{
  "error": {
    "code": "invalid_state",
    "message": "Only pending transactions can be cancelled (this one is cancelled).",
    "request_id": "req_01M47EK1R0AYZS20ZCG4XVHMVN"
  }
}

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.
JSON
{ "metadata": { "cart_id": "c_88", "customer_id": 4512, "gift": false } }

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.