Verify Transactions

Learn how to verify checkout transactions using the Nomba API

Verify by Order Reference

Look up a transaction using your order reference or the Nomba transaction ID.

Fetch Checkout Transaction (Production)

Retrieve full checkout order details including card and transfer info.

Which endpoint should I use?

There are two ways to verify a checkout transaction. Choose based on your environment and what you need:

Endpoint	Method	Environment	Use when
/v1/transactions/accounts/single	GET	Sandbox + Production	You want to confirm status: SUCCESS before delivering value. Works with orderReference, orderId, transactionRef, or merchantTxRef as query params.
/v1/checkout/transaction	GET	Production only	You need full checkout order details (card info, transfer details, order metadata).

Always verify transactions before providing goods or services to your customer — even if you received a webhook.

Verify with credentials from the region that took the payment. Nigeria and DRC transactions are held in separate systems. If you hold both a Nigerian and a DRC account, a payment collected in CDF or USD on your DRC account must be looked up with your DRC credentials — a Nigerian token will return Transaction not found for it, whichever reference you pass.

Option 1: Verify via /v1/transactions/accounts/single

This endpoint works in both sandbox and production. Pass the orderReference (the reference you supplied on the order), the orderId (the value returned as orderReference in the create-order response), or the transactionRef (the Nomba transaction ID from the webhook) as a query parameter.

The key field to check in the response is data.status. A successful payment returns "status": "SUCCESS".

Verify by orderReference

  curl --request GET \
    --url 'https://api.nomba.com/v1/transactions/accounts/single?orderReference=90e81e8a-bc14-4ebf-89c0-57da801cca68' \
    --header 'Authorization: Bearer <token>' \
    --header 'accountId: <accountid>'

For sandbox transactions, use the sandbox base URL: https://sandbox.nomba.com/v1/transactions/accounts/single. See Sandbox Testing for details on looking up sandbox transactions.

Option 2: Get Checkout Transaction (Production only)

This endpoint returns full checkout order details including card information, transfer details, and order metadata. It is useful when you need richer data than the basic transaction lookup provides — for example, to display order details on a receipt page.

This endpoint is only available in the production environment. For sandbox verification, use POST /v1/transactions/accounts with the transaction reference — see Sandbox Testing.

To fetch a checkout transaction, send a GET request to this endpoint /v1/checkout/transaction.

Read transactionDetails.status to confirm the payment. PAYMENT SUCCESSFUL means the payment completed; PENDING means it is still in progress and FAILED PAYMENT means it did not complete.

transactionDetails.statusCode is the card processor response code, not the payment status. It is empty on rails that do not go through a card processor, such as mobile money, so it cannot be used to confirm a payment. Use transactionDetails.status.

Request

  curl --request GET \
    --url 'https://api.nomba.com/v1/checkout/transaction?idType=ORDER_REFERENCE&id=68da39e0-2ce4-4ea6-9def-5*********' \
    --header 'Authorization: Bearer <token>' \
    --header 'accountId: <accountid>'