Cards & checkout

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.

International cards

On the sandbox checkout page, the card channel has a Nigeria / International toggle. Use the International side to test payments from foreign cards, the same way customers pay in production. International cards always go through 3D Secure (3DS), so expect a bank verification step after you submit the card. In sandbox, that step is a 3DS test page where you choose how authentication ends.

Scenario	How to trigger it	Expected result
Success after 3DS	Card `4000 0000 0000 2503`, then Complete authentication on the 3DS test page	Payment approved. A `payment_success` webhook is sent
3DS failed	Card `4000 0000 0000 2503`, then Fail authentication	Payment failed. A `payment_failed` webhook is sent
3DS abandoned	Card `4000 0000 0000 2503`, then Cancel or close the 3DS test page	Payment not completed. No transaction is recorded and no webhook is sent
Declined by the bank	Card `5484 4972 1831 7651`	Declined before 3DS. A `payment_failed` webhook is sent

Any cardholder name, 3-digit CVC and future expiry date work. No PIN or OTP is needed for international cards. Supported currencies: create the checkout order in USD, GBP or EUR. The toggle also appears on NGN orders.

Every sandbox account can test international card payments. In production, international card payments only work once your business is approved for them. Contact support to apply.

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

International cards

Quick sandbox flow

Fetch Sandbox Checkout Transactions

​Test card details

​Test cards

​PIN and OTP

​Transaction scenarios

​International cards

​Quick sandbox flow

​Fetch Sandbox Checkout Transactions

Test card details

Test cards

PIN and OTP

Transaction scenarios

International cards

Quick sandbox flow

Fetch Sandbox Checkout Transactions