Testing

To use the sandbox environment, you must generate a token using your test credentials (clientId and clientSecret from the dashboard) and the sandbox base URL (https://sandbox.nomba.com). Using the wrong URL or credentials will cause authentication failures. See the Environment page for details.

Test cards are provided for use in the sandbox environment only. They cannot be used for real transactions and should not be used in production.

Test Card Details

Use the following card details when testing transactions in a sandbox or staging environment.

Test cards

Card Number	Network	Outcome
`5434 6210 7425 2808`	Mastercard	OTP required → approved
`4000 0000 0000 2503`	Visa	3DS authentication required
`5484 4972 1831 7651`	Mastercard	Declined — “do not honor”

For all cards: CVV and expiry are not validated — any 3-digit CVV and any future expiry date are accepted. The card number alone determines the outcome.

PIN and OTP

Field	Value	Notes
Card PIN	`9999`	Used during card detail submission
OTP — Approved	`9999`	Payment succeeds
OTP — Timeout	`1234`	Payment fails with timeout message
OTP — Invalid	`5464`	Payment fails with invalid OTP message

Transaction scenarios

Scenario	How to trigger	Expected outcome
Successful card payment	Card `5434 6210 7425 2808` + OTP `9999`	Transaction Approved
Declined card	Card `5484 4972 1831 7651`	do not honor
OTP timeout	OTP `1234`	Payment timed out
Invalid OTP	OTP `5464`	Invalid OTP
Insufficient funds	Amount greater than `500,000`	Transaction Declined
Expired card	Expiry `12/20`	Transaction Declined

This test card should only be used in development or staging environments. Do not attempt real transactions with this card.

Quick Sandbox Flow

Follow these steps to run a checkout transaction end-to-end in the sandbox:

Generate a sandbox token — Use https://sandbox.nomba.com/v1/auth/token/issue with your test clientId and clientSecret
Create a checkout order — POST https://sandbox.nomba.com/v1/checkout/order with your sandbox token
Open the checkout link — Load the checkoutLink from the response in a browser
Enter the test card — Use the card number, CVV, and expiry date from the table above
Enter the test OTP — Use 9999 for a successful transaction
Verify the transaction — Use the transactionRef from the webhook or the orderReference you provided

For a detailed walkthrough with request/response examples, see Sandbox Testing.

Fetch Sandbox Checkout Transactions

You can retrieve the details of a specific transaction performed in the sandbox environment by sending a POST request with the transaction reference. This is useful for testing how your system handles different transaction outcomes (e.g., success, failure, pending).

   curl --request POST \
   --url https://sandbox.nomba.com/v1/transactions/accounts \
   --header 'Authorization: Bearer <token>' \
   --header 'Content-Type: application/json' \
   --header 'accountId: <accountid>' \
   --data '
      {
         "transactionRef": "WEB-ONLINE_C-SANDBOXDFC05-693cd007-cd1e-4ea6-xxxxxxxxxx" 
      }
   '

   {
      "code": "00",
      "description": "success",
      "data": {
         "results": [
               {
                  "id": "WEB-ONLINE_C-SANDBOXDFC05-693cd007-cd1e-4ea6-xxxxxxxxxx",
                  "status": "PAYMENT_SUCCESSFUL",
                  "amount": 4000,
                  "fixedCharge": 123,
                  "source": "web",
                  "type": "online_checkout",
                  "gatewayMessage": "payment successful",
                  "customerBillerId": "543462 **** **** 2808",
                  "timeCreated": "2023-09-08T19:26:34.657000Z",
                  "timeUpdated": "2023-09-08T19:26:34.900000Z",
                  "walletCurrency": "NGN",
                  "userId": "dfc05ca1-4xx5-41dd-xx41-2d362dxxxxx3",
                  "onlineCheckoutOrderId": "a1b2c3d4-e5f6-47a8-xxxx-xxxxxxxxxxxx",
                  "onlineCheckoutOrderReference": "fd3002af-d48b-40a0-adba-xxxxxxxxxxxx",
                  "onlineCheckoutTokenizedCardPayment": "false",
                  "onlineCheckoutCardPan": "543462 **** **** 2808",
                  "onlineCheckoutCurrency": "NGN",
                  "onlineCheckoutCustomerEmail": "[email protected]",
                  "onlineCheckoutAmount": "4000",
                  "onlineCheckoutPaymentMethod": "card_payment",
                  "onlineCheckoutTokenKey": "N/A",
                  "onlineCheckoutCardType": "Mastercard",
                  "currency": "NGN",
                  "entryType": "CREDIT",
                  "merchantTxRef": "c90d-4bxx-ad0f"
               }
         ],
         "cursor": "xchbaVFsjdsbaADddd"
      }
   }

Introduction

Getting Started

Products

API Basics

Guides

Test Card Details

Test cards

PIN and OTP

Transaction scenarios

Quick Sandbox Flow

Fetch Sandbox Checkout Transactions

​Test Card Details

​Test cards

​PIN and OTP

​Transaction scenarios

​Quick Sandbox Flow

​Fetch Sandbox Checkout Transactions

Test Card Details

Test cards

PIN and OTP

Transaction scenarios

Quick Sandbox Flow

Fetch Sandbox Checkout Transactions