Skip to content
YusrDocs

API reference

Transactions

A transaction issues a one-time account number for a single payment. Create one per checkout attempt, show the account details to your customer, then confirm the payment by webhook, realtime socket or polling.

Transactions endpoints
get/v1/transactionsList transactions
post/v1/transactionsCreate a transaction
get/v1/transactions/{id}Retrieve a transaction
post/v1/transactions/{id}/cancelCancel a pending transaction
post/v1/transactions/{id}/client-tokenCreate a browser client token

Read the Transactions guide for the concepts behind these endpoints.

List transactions

get/v1/transactions

Query parameters

Query parameters
referencestring
statusstring

One of pending, paid, underpaid, overpaid, expired, late_payment, reversed, failed, cancelled

fromstring (date-time)
tostring (date-time)
limitinteger

1–100, default 20

starting_afterstring

Cursor: the next_cursor from the previous page.

curl "https://api.yusr.ng/v1/transactions?status=paid&limit=20" \
  -H "Authorization: Bearer sk_test_..."

Responses

200A page of transactions
Show response attributes
Response attributes
objectstringrequired

always "list"

dataarray of objectrequired
Show child attributes
idstringrequired

Yusr transaction ID, prefixed txn_.

objectstringrequired

always "transaction"

modestringrequired

One of test, live

statusstringrequired

One of pending, paid, underpaid, overpaid, expired, late_payment, reversed, failed, cancelled

amountintegerrequired

Amount requested, in kobo.

amount_receivedintegerrequired

Sum of all payments received, in kobo.

feeintegerrequired

Yusr fee in kobo.

fee_bearerstringrequired

One of merchant, customer

net_amountintegerrequired

Amount settled to you after fees, in kobo.

currencystringrequired

always "NGN"

referencestringrequired
descriptionstring | nullrequired
customerobjectrequired
Show child attributes
namestringrequired
emailstringrequired
phonestring | nullrequired
paymentobjectrequired
Show child attributes
account_numberstringrequired
bank_namestringrequired
account_namestringrequired
amountintegerrequired

Exact amount the payer must transfer, in kobo.

expires_atstringrequired
flagsobjectrequired
Show child attributes
overpaidbooleanrequired
underpaidbooleanrequired
latebooleanrequired
paymentsarray of objectrequired
Show child attributes
idstringrequired
amountintegerrequired
payer_namestring | nullrequired
payer_bankstring | nullrequired
payer_account_numberstring | nullrequired

Masked, last 4 digits only.

received_atstringrequired
metadataobject of anyrequired
created_atstringrequired
updated_atstringrequired
paid_atstring | nullrequired
expires_atstringrequired
has_morebooleanrequired
next_cursorstring | nullrequired
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
      "object": "transaction",
      "mode": "live",
      "status": "paid",
      "amount": 2500000,
      "amount_received": 2500000,
      "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": null
      },
      "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": [
        {
          "id": "pay_01JA9QB2T3W4X5Y6Z7A8B9C0D1",
          "amount": 2500000,
          "payer_name": "ADA OBI",
          "payer_bank": "Partner Bank",
          "payer_account_number": "******4321",
          "received_at": "2026-10-06T14:07:12.000Z"
        }
      ],
      "metadata": {
        "cart_id": "c_88"
      },
      "created_at": "2026-10-06T14:00:00.000Z",
      "updated_at": "2026-10-06T14:07:12.000Z",
      "paid_at": "2026-10-06T14:07:12.000Z",
      "expires_at": "2026-10-06T14:30:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F"
}
Error responses
StatusMeaningError codes
400Invalid requestinvalid_request
401Authentication failedauthentication_failed
429Rate limited — see Retry-Afterrate_limited
Try it in the sandbox

Create a transaction

post/v1/transactions

Issues a one-time account number for the payer to transfer the exact payment.amount to before payment.expires_at.

Headers

Headers
Idempotency-Keystring

Unique key (≤ 255 chars). Retrying with the same key and body within 24 h returns the original response.

max length 255

Request bodyapplication/json

Request body attributes
amountintegerrequired

Amount in kobo. ₦25,000.00 is 2500000.

> 0, ≤ 100000000000

currencystring

always "NGN", default "NGN"

referencestringrequired

Your unique reference for this payment.

min length 1, max length 100, pattern ^[A-Za-z0-9._\-:/]+$

descriptionstring

max length 200

customerobjectrequired
Show child attributes
namestringrequired

min length 1, max length 100

emailstringrequired

max length 200, email

phonestring

pattern ^\+?[0-9]{7,15}$

expires_ininteger

Seconds until the account expires. Default 1800 (30 minutes).

600–259200, default 1800

metadataobject of string | number | boolean | null
curl -X POST "https://api.yusr.ng/v1/transactions" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 2500000,
  "reference": "order-1042",
  "description": "Order #1042",
  "customer": {
    "name": "Ada Obi",
    "email": "ada@example.com"
  },
  "expires_in": 1800,
  "metadata": {
    "cart_id": "c_88"
  }
}'

Responses

201Created
Show response attributes
Response attributes
idstringrequired

Yusr transaction ID, prefixed txn_.

objectstringrequired

always "transaction"

modestringrequired

One of test, live

statusstringrequired

One of pending, paid, underpaid, overpaid, expired, late_payment, reversed, failed, cancelled

amountintegerrequired

Amount requested, in kobo.

amount_receivedintegerrequired

Sum of all payments received, in kobo.

feeintegerrequired

Yusr fee in kobo.

fee_bearerstringrequired

One of merchant, customer

net_amountintegerrequired

Amount settled to you after fees, in kobo.

currencystringrequired

always "NGN"

referencestringrequired
descriptionstring | nullrequired
customerobjectrequired
Show child attributes
namestringrequired
emailstringrequired
phonestring | nullrequired
paymentobjectrequired
Show child attributes
account_numberstringrequired
bank_namestringrequired
account_namestringrequired
amountintegerrequired

Exact amount the payer must transfer, in kobo.

expires_atstringrequired
flagsobjectrequired
Show child attributes
overpaidbooleanrequired
underpaidbooleanrequired
latebooleanrequired
paymentsarray of objectrequired
Show child attributes
idstringrequired
amountintegerrequired
payer_namestring | nullrequired
payer_bankstring | nullrequired
payer_account_numberstring | nullrequired

Masked, last 4 digits only.

received_atstringrequired
metadataobject of anyrequired
created_atstringrequired
updated_atstringrequired
paid_atstring | nullrequired
expires_atstringrequired
Response 201
{
  "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
  "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": null
  },
  "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"
  },
  "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"
}
Error responses
StatusMeaningError codes
400Invalid requestinvalid_request
401Authentication failedauthentication_failed
403Forbiddensandbox_onlymerchant_not_livemerchant_suspendedip_not_allowed
409Conflict (duplicate reference, idempotency conflict, invalid state)duplicate_referenceidempotency_conflictidempotency_in_progressinvalid_state
422Amount out of range or limit exceededamount_out_of_rangelimit_exceeded
429Rate limited — see Retry-Afterrate_limited
500Internal error — retry with the same Idempotency-Keyinternal_error
502Processing error — the payment account could not be issued; retry with the same Idempotency-Keyprocessing_error
503Service unavailable — retry with the same Idempotency-Keyservice_unavailable
Try it in the sandbox

Retrieve a transaction

get/v1/transactions/{id}

Use for polling when a webhook is late. Poll at most once per second per transaction; 5 seconds is recommended.

Path parameters

Path parameters
idstringrequired
curl "https://api.yusr.ng/v1/transactions/txn_01JA9Q3K7M2VXR8D5N0B4C6E2F" \
  -H "Authorization: Bearer sk_test_..."

Responses

200The transaction
Show response attributes
Response attributes
idstringrequired

Yusr transaction ID, prefixed txn_.

objectstringrequired

always "transaction"

modestringrequired

One of test, live

statusstringrequired

One of pending, paid, underpaid, overpaid, expired, late_payment, reversed, failed, cancelled

amountintegerrequired

Amount requested, in kobo.

amount_receivedintegerrequired

Sum of all payments received, in kobo.

feeintegerrequired

Yusr fee in kobo.

fee_bearerstringrequired

One of merchant, customer

net_amountintegerrequired

Amount settled to you after fees, in kobo.

currencystringrequired

always "NGN"

referencestringrequired
descriptionstring | nullrequired
customerobjectrequired
Show child attributes
namestringrequired
emailstringrequired
phonestring | nullrequired
paymentobjectrequired
Show child attributes
account_numberstringrequired
bank_namestringrequired
account_namestringrequired
amountintegerrequired

Exact amount the payer must transfer, in kobo.

expires_atstringrequired
flagsobjectrequired
Show child attributes
overpaidbooleanrequired
underpaidbooleanrequired
latebooleanrequired
paymentsarray of objectrequired
Show child attributes
idstringrequired
amountintegerrequired
payer_namestring | nullrequired
payer_bankstring | nullrequired
payer_account_numberstring | nullrequired

Masked, last 4 digits only.

received_atstringrequired
metadataobject of anyrequired
created_atstringrequired
updated_atstringrequired
paid_atstring | nullrequired
expires_atstringrequired
Response 200
{
  "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
  "object": "transaction",
  "mode": "live",
  "status": "paid",
  "amount": 2500000,
  "amount_received": 2500000,
  "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": null
  },
  "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": [
    {
      "id": "pay_01JA9QB2T3W4X5Y6Z7A8B9C0D1",
      "amount": 2500000,
      "payer_name": "ADA OBI",
      "payer_bank": "Partner Bank",
      "payer_account_number": "******4321",
      "received_at": "2026-10-06T14:07:12.000Z"
    }
  ],
  "metadata": {
    "cart_id": "c_88"
  },
  "created_at": "2026-10-06T14:00:00.000Z",
  "updated_at": "2026-10-06T14:07:12.000Z",
  "paid_at": "2026-10-06T14:07:12.000Z",
  "expires_at": "2026-10-06T14:30:00.000Z"
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
404Not foundnot_found
429Rate limited — see Retry-Afterrate_limited
Try it in the sandbox

Cancel a pending transaction

post/v1/transactions/{id}/cancel

Path parameters

Path parameters
idstringrequired

Headers

Headers
Idempotency-Keystring

Unique key (≤ 255 chars). Retrying with the same key and body within 24 h returns the original response.

max length 255

curl -X POST "https://api.yusr.ng/v1/transactions/txn_01JA9Q3K7M2VXR8D5N0B4C6E2F/cancel" \
  -H "Authorization: Bearer sk_test_..."

Responses

200Cancelled
Show response attributes
Response attributes
idstringrequired

Yusr transaction ID, prefixed txn_.

objectstringrequired

always "transaction"

modestringrequired

One of test, live

statusstringrequired

One of pending, paid, underpaid, overpaid, expired, late_payment, reversed, failed, cancelled

amountintegerrequired

Amount requested, in kobo.

amount_receivedintegerrequired

Sum of all payments received, in kobo.

feeintegerrequired

Yusr fee in kobo.

fee_bearerstringrequired

One of merchant, customer

net_amountintegerrequired

Amount settled to you after fees, in kobo.

currencystringrequired

always "NGN"

referencestringrequired
descriptionstring | nullrequired
customerobjectrequired
Show child attributes
namestringrequired
emailstringrequired
phonestring | nullrequired
paymentobjectrequired
Show child attributes
account_numberstringrequired
bank_namestringrequired
account_namestringrequired
amountintegerrequired

Exact amount the payer must transfer, in kobo.

expires_atstringrequired
flagsobjectrequired
Show child attributes
overpaidbooleanrequired
underpaidbooleanrequired
latebooleanrequired
paymentsarray of objectrequired
Show child attributes
idstringrequired
amountintegerrequired
payer_namestring | nullrequired
payer_bankstring | nullrequired
payer_account_numberstring | nullrequired

Masked, last 4 digits only.

received_atstringrequired
metadataobject of anyrequired
created_atstringrequired
updated_atstringrequired
paid_atstring | nullrequired
expires_atstringrequired
Response 200
{
  "id": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
  "object": "transaction",
  "mode": "live",
  "status": "cancelled",
  "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": null
  },
  "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"
  },
  "created_at": "2026-10-06T14:00:00.000Z",
  "updated_at": "2026-10-06T14:02:41.000Z",
  "paid_at": null,
  "expires_at": "2026-10-06T14:30:00.000Z"
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
404Not foundnot_found
409Conflict (duplicate reference, idempotency conflict, invalid state)duplicate_referenceidempotency_conflictidempotency_in_progressinvalid_state
Try it in the sandbox

Create a browser client token

post/v1/transactions/{id}/client-token

Short-lived (30 min), read-only token scoped to one transaction, for subscribing a browser to realtime updates without exposing your secret key.

Path parameters

Path parameters
idstringrequired
curl -X POST "https://api.yusr.ng/v1/transactions/txn_01JA9Q3K7M2VXR8D5N0B4C6E2F/client-token" \
  -H "Authorization: Bearer sk_test_..."

Responses

201Token
Show response attributes
Response attributes
objectstringrequired

always "client_token"

tokenstringrequired
transactionstringrequired
expires_atstringrequired
Response 201
{
  "object": "client_token",
  "token": "ct_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0eG5fMDFKQTlRM0s3TTJWIn0.4bX9yVb0",
  "transaction": "txn_01JA9Q3K7M2VXR8D5N0B4C6E2F",
  "expires_at": "2026-10-06T14:30:00.000Z"
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
404Not foundnot_found
Try it in the sandbox