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.
| get | /v1/transactionsList transactions | List transactions |
| post | /v1/transactionsCreate a transaction | Create a transaction |
| get | /v1/transactions/{id}Retrieve a transaction | Retrieve a transaction |
| post | /v1/transactions/{id}/cancelCancel a pending transaction | Cancel a pending transaction |
| post | /v1/transactions/{id}/client-tokenCreate a browser client token | Create a browser client token |
Read the Transactions guide for the concepts behind these endpoints.
List transactions
/v1/transactionsQuery parameters
referencestring | |
statusstring | One of |
fromstring (date-time) | |
tostring (date-time) | |
limitinteger | 1–100, default 20 |
starting_afterstring | Cursor: the |
Responses
Show response attributesHide response attributes
objectstringrequired | always "list" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dataarray of objectrequired | Show child attributesHide child attributes
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
has_morebooleanrequired | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
next_cursorstring | nullrequired |
Create a transaction
/v1/transactionsIssues a one-time account number for the payer to transfer the exact payment.amount to before payment.expires_at.
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
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 attributesHide child attributes
| ||||||
expires_ininteger | Seconds until the account expires. Default 1800 (30 minutes). 600–259200, default 1800 | ||||||
metadataobject of string | number | boolean | null |
Responses
Show response attributesHide response attributes
idstringrequired | Yusr transaction ID, prefixed txn_. | ||||||||||||
objectstringrequired | always "transaction" | ||||||||||||
modestringrequired | One of | ||||||||||||
statusstringrequired | One of | ||||||||||||
amountintegerrequired | Amount requested, in kobo. | ||||||||||||
amount_receivedintegerrequired | Sum of all payments received, in kobo. | ||||||||||||
feeintegerrequired | Yusr fee in kobo. | ||||||||||||
fee_bearerstringrequired | One of | ||||||||||||
net_amountintegerrequired | Amount settled to you after fees, in kobo. | ||||||||||||
currencystringrequired | always "NGN" | ||||||||||||
referencestringrequired | |||||||||||||
descriptionstring | nullrequired | |||||||||||||
customerobjectrequired | Show child attributesHide child attributes
| ||||||||||||
paymentobjectrequired | Show child attributesHide child attributes
| ||||||||||||
flagsobjectrequired | Show child attributesHide child attributes
| ||||||||||||
paymentsarray of objectrequired | Show child attributesHide child attributes
| ||||||||||||
metadataobject of anyrequired | |||||||||||||
created_atstringrequired | |||||||||||||
updated_atstringrequired | |||||||||||||
paid_atstring | nullrequired | |||||||||||||
expires_atstringrequired |
Retrieve a transaction
/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
idstringrequired |
Responses
Show response attributesHide response attributes
idstringrequired | Yusr transaction ID, prefixed txn_. | ||||||||||||
objectstringrequired | always "transaction" | ||||||||||||
modestringrequired | One of | ||||||||||||
statusstringrequired | One of | ||||||||||||
amountintegerrequired | Amount requested, in kobo. | ||||||||||||
amount_receivedintegerrequired | Sum of all payments received, in kobo. | ||||||||||||
feeintegerrequired | Yusr fee in kobo. | ||||||||||||
fee_bearerstringrequired | One of | ||||||||||||
net_amountintegerrequired | Amount settled to you after fees, in kobo. | ||||||||||||
currencystringrequired | always "NGN" | ||||||||||||
referencestringrequired | |||||||||||||
descriptionstring | nullrequired | |||||||||||||
customerobjectrequired | Show child attributesHide child attributes
| ||||||||||||
paymentobjectrequired | Show child attributesHide child attributes
| ||||||||||||
flagsobjectrequired | Show child attributesHide child attributes
| ||||||||||||
paymentsarray of objectrequired | Show child attributesHide child attributes
| ||||||||||||
metadataobject of anyrequired | |||||||||||||
created_atstringrequired | |||||||||||||
updated_atstringrequired | |||||||||||||
paid_atstring | nullrequired | |||||||||||||
expires_atstringrequired |
Cancel a pending transaction
/v1/transactions/{id}/cancelPath parameters
idstringrequired |
Headers
Idempotency-Keystring | Unique key (≤ 255 chars). Retrying with the same key and body within 24 h returns the original response. max length 255 |
Responses
Show response attributesHide response attributes
idstringrequired | Yusr transaction ID, prefixed txn_. | ||||||||||||
objectstringrequired | always "transaction" | ||||||||||||
modestringrequired | One of | ||||||||||||
statusstringrequired | One of | ||||||||||||
amountintegerrequired | Amount requested, in kobo. | ||||||||||||
amount_receivedintegerrequired | Sum of all payments received, in kobo. | ||||||||||||
feeintegerrequired | Yusr fee in kobo. | ||||||||||||
fee_bearerstringrequired | One of | ||||||||||||
net_amountintegerrequired | Amount settled to you after fees, in kobo. | ||||||||||||
currencystringrequired | always "NGN" | ||||||||||||
referencestringrequired | |||||||||||||
descriptionstring | nullrequired | |||||||||||||
customerobjectrequired | Show child attributesHide child attributes
| ||||||||||||
paymentobjectrequired | Show child attributesHide child attributes
| ||||||||||||
flagsobjectrequired | Show child attributesHide child attributes
| ||||||||||||
paymentsarray of objectrequired | Show child attributesHide child attributes
| ||||||||||||
metadataobject of anyrequired | |||||||||||||
created_atstringrequired | |||||||||||||
updated_atstringrequired | |||||||||||||
paid_atstring | nullrequired | |||||||||||||
expires_atstringrequired |
Create a browser client token
/v1/transactions/{id}/client-tokenShort-lived (30 min), read-only token scoped to one transaction, for subscribing a browser to realtime updates without exposing your secret key.
Path parameters
idstringrequired |
Responses
Show response attributesHide response attributes
objectstringrequired | always "client_token" |
tokenstringrequired | |
transactionstringrequired | |
expires_atstringrequired |