Sandbox Testing

All sandbox API calls must use the base URL https://sandbox.nomba.com and your sandbox credentials. Mixing production credentials with the sandbox URL (or vice versa) will cause authentication errors. See Environment for details.

Before you start

Get your sandbox credentials

Log in to the Nomba dashboard, navigate to API Keys, and copy your test clientId, clientSecret, and accountId. These are generated alongside your production credentials and only work with https://sandbox.nomba.com.

Generate a sandbox access token

Exchange your test credentials for an access token. The sandbox token is short-lived — if you get 401 errors mid-test, generate a new one.

curl --request POST \
  --url https://sandbox.nomba.com/v1/auth/token/issue \
  --header 'Content-Type: application/json' \
  --header 'accountId: <your-sandbox-accountId>' \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "<your-sandbox-clientId>",
    "client_secret": "<your-sandbox-clientSecret>"
  }'

Response

{
  "code": "00",
  "description": "Success",
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "01h4gdx2...",
    "expiresAt": "2026-01-01T12:00:00Z"
  }
}

All sandbox checkout endpoints are under the /sandbox/checkout/ path prefix, not /v1/checkout/. This is the key difference between sandbox and production.

Card payment flow

Step 1 — Create a checkout order

curl --request POST \
  --url https://sandbox.nomba.com/sandbox/checkout/order \
  --header 'Authorization: Bearer <sandbox-token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <your-sandbox-accountId>' \
  --data '{
    "order": {
      "orderReference": "test-order-001",
      "amount": "400000.00",
      "currency": "NGN",
      "customerEmail": "[email protected]",
      "callbackUrl": "https://merchant.com/callback"
    }
  }'

Response

{
  "code": "00",
  "description": "Success",
  "data": {
    "checkoutLink": "https://checkout.nomba.com/sandbox/<encrypted-ref>",
    "orderReference": "test-order-001"
  }
}

If you omit orderReference, Nomba generates one in the format {accountId_prefix}_{timestamp} and returns it in the response. Use that value for all subsequent calls.

The sandbox checkout link has the format https://checkout.nomba.com/sandbox/{encryptedRef} — note the /sandbox/ segment, which distinguishes it from production links. Orders and their data are stored for 48 hours before expiring.

Step 2 — Submit card details

Submit the test card details to the checkout. The response depends entirely on which card number you use.

Test card numbers

Use one of these three cards to simulate different payment outcomes:

Card Number	Network	Outcome	Next step
`5434621074252808`	Mastercard	OTP required (T0 response)	Submit OTP to complete
`4000000000002503`	Visa	3DS authentication required (S0 response)	Handle 3DS redirect
`5484497218317651`	Mastercard	Declined — “do not honor”	No further steps; payment failed

Card expiry, CVV, and PIN values are not validated in the sandbox — any values are accepted. Only the card number determines the outcome.

Step 3 - Submit Card Pin (if required)

Enter any 4-digit PIN. The examples on this page use 9999.

Declined card (5484497218317651) response:

Submit Card Detail for Failed Transaction

Step 4 — Submit OTP

After submitting the successful Mastercard (5434621074252808), the customer is prompted for an OTP. Submit one of the following test values to control the outcome:

OTP	Outcome	Message
`9999`	Approved	”Approved by Financial Institution”
`1234`	Timeout	”Your payment has exceeded the time required to pay”
`5464`	Invalid OTP	”Invalid OTP”

Successful card (5434621074252808) response:

On a successful OTP submission, Nomba immediately fires a webhook to your configured callbackUrl with a payment_success event. See Webhook payload below.

Step 4 — Verify the transaction

Use the sandbox-specific fetch endpoint to confirm the transaction result:

curl --request GET \
  --url 'https://sandbox.nomba.com/sandbox/checkout/transaction?idType=orderReference&id=test-order-001' \
  --header 'Authorization: Bearer <sandbox-token>' \
  --header 'accountId: <your-sandbox-accountId>'

Response

{
  "code": "00",
  "description": "Success",
  "data": {
    "success": true,
    "message": "PAYMENT SUCCESSFUL",
    "order": {
      "orderId": "a1b2c3d4-e5f6-47a8-xxxx-xxxxxxxxxxxx",
      "orderReference": "test-order-001",
      "amount": "4000.00",
      "currency": "NGN",
      "customerEmail": "[email protected]"
    },
    "transactionDetails": {
      "transactionDate": "2026-03-31T10:00:00Z",
      "paymentReference": "WEB-ONLINE_C-abc123-550e4c3a-...",
      "statusCode": "PAYMENT SUCCESSFUL",
      "tokenizedCardPayment": "false"
    },
    "cardDetails": {
      "cardPan": "543462 **** **** 2808",
      "cardType": "MASTERCARD",
      "cardCurrency": "NGN"
    }
  }
}

You can query by idType=orderReference or idType=orderId. The id value changes accordingly.

The sandbox transaction fetch endpoint is GET /sandbox/checkout/transaction — not GET /v1/checkout/transaction, which is production-only. Transaction IDs in the sandbox follow the format WEB-ONLINE_C-{first6charsOfAccountId}-{UUID}.

International card flow

Test payments from foreign cards on the International side of the card channel. The flow is the same as production, including the 3D Secure (3DS) step every international card goes through. Every sandbox account can use it. In production, international card payments need approval first.

Step 1 — Create an order in USD, GBP or EUR

Use the same POST /sandbox/checkout/order request as above, with "currency": "USD" (or GBP, EUR). Open the checkoutLink, choose Card, then switch to International. The page shows the order amount and currency, plus the fee if your fee setting charges the customer.

Step 2 — Pay with a test card

Card number	Then	Result
`4000000000002503`	Complete authentication on the 3DS test page	Approved. `payment_success` webhook
`4000000000002503`	Fail authentication	Failed. `payment_failed` webhook
`4000000000002503`	Cancel, or close the 3DS test page	Not completed. No transaction and no webhook
`5484497218317651`	No 3DS step	Declined. `payment_failed` webhook

Any cardholder name, CVC and future expiry date work.

Step 3 — Verify the transaction

Fetch the result with GET /sandbox/checkout/transaction, exactly as for Nigerian cards. International card payments have cardDetails for the foreign card:

Response (success)

{
  "code": "00",
  "description": "success",
  "data": {
    "success": true,
    "order": {
      "orderId": "a1b2c3d4-e5f6-47a8-xxxx-xxxxxxxxxxxx",
      "orderReference": "test-order-002",
      "amount": "25.00",
      "currency": "USD",
      "customerEmail": "[email protected]"
    },
    "transactionDetails": {
      "transactionDate": "2026-10-02T10:00:00Z",
      "paymentReference": "8f1c2b7e-...",
      "tokenizedCardPayment": "false"
    },
    "cardDetails": {
      "cardPan": "400000******2503",
      "cardType": "VISA",
      "cardCurrency": "USD"
    }
  }
}

A failed payment returns the same shape with "success": false.

Webhooks

A successful international payment sends payment_success. A failed or declined one sends payment_failed. Both have the same shape as Nigerian card webhooks, with paymentMethod set to pay_with_stripe_card (the value production sends) and the foreign card in customer:

{
  "event_type": "payment_success",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "merchant": { "userId": "<your-accountId>" },
    "transaction": {
      "fee": 0.28,
      "type": "online_checkout",
      "transactionId": "WEB-ONLINE_C-abc123-550e4c3a-0af4-4887-a089-xxxx",
      "merchantTxRef": "txref-1790935200",
      "transactionAmount": 25.00,
      "time": "2026-10-02T10:00:00Z"
    },
    "customer": { "billerId": "400000******2503", "productId": "400000" },
    "order": {
      "amount": 25.00,
      "orderId": "a1b2c3d4-e5f6-47a8-xxxx-xxxxxxxxxxxx",
      "accountId": "<your-accountId>",
      "customerEmail": "[email protected]",
      "orderReference": "test-order-002",
      "paymentMethod": "pay_with_stripe_card",
      "currency": "USD"
    }
  }
}

{
  "event_type": "payment_failed",
  "requestId": "6f9619ff-8b86-d011-b42d-00c04fc964ff",
  "data": {
    "merchant": { "userId": "<your-accountId>" },
    "transaction": {
      "fee": 0.28,
      "type": "online_checkout",
      "transactionId": "WEB-ONLINE_C-abc123-7c9e6679-7425-40de-944b-xxxx",
      "merchantTxRef": "txref-1790935260",
      "transactionAmount": 25.00,
      "time": "2026-10-02T10:01:00Z"
    },
    "customer": { "billerId": "548449******7651", "productId": "548449" },
    "order": {
      "amount": 25.00,
      "orderId": "a1b2c3d4-e5f6-47a8-xxxx-xxxxxxxxxxxx",
      "accountId": "<your-accountId>",
      "customerEmail": "[email protected]",
      "orderReference": "test-order-002",
      "paymentMethod": "pay_with_stripe_card",
      "currency": "USD"
    }
  }
}

Sandbox-only differences: transaction IDs, merchantTxRef and card numbers are test values, and the fee is a fixed test amount.

International pay-by-bank flow

Test payments from UK and European bank accounts on the Bank App channel. In production, the customer picks their bank and approves the payment in their banking app. In sandbox, a test page stands in for the bank’s app, so you choose how the payment ends. Every sandbox account can use it. In production, pay-by-bank needs approval first.

Step 1 — Create an order

Use the same POST /sandbox/checkout/order request as above. Bank App is offered for every order currency except USD and CDF. Open the checkoutLink and choose Bank App.

Step 2 — Choose a country and bank

Select the customer’s country (United Kingdom, Germany, France, Netherlands, Spain or Belgium) and a bank, for example Monzo or Barclays, then select Continue to Monzo (or your chosen bank). The test bank page shows the bank and the amount.

Step 3 — Choose the outcome on the test bank page

Action	Result
Authorise payment	Approved. `payment_success` webhook
Decline payment	Failed with “Your bank declined the payment.” `payment_failed` webhook
Cancel, or close the test bank page	Not completed. No transaction and no webhook. The customer can choose another bank

An order can be authorised only once. A second authorisation fails with “This order has already been paid.” and records nothing.

Step 4 — Verify the transaction

Fetch the result with GET /sandbox/checkout/transaction, as for card payments. Pay-by-bank payments have no cardDetails:

Response (success)

{
  "code": "00",
  "description": "success",
  "data": {
    "success": true,
    "message": "PAYMENT SUCCESSFUL",
    "order": {
      "orderId": "a1b2c3d4-e5f6-47a8-xxxx-xxxxxxxxxxxx",
      "orderReference": "test-order-003",
      "amount": "50000.00",
      "currency": "NGN",
      "customerEmail": "[email protected]"
    },
    "transactionDetails": {
      "transactionDate": "2026-10-05T10:00:00Z",
      "paymentReference": "3b8f6d2a-...",
      "tokenizedCardPayment": "false"
    }
  }
}

A declined payment returns the same shape with "success": false and "message": "Your bank declined the payment.".

Webhooks

An authorised payment sends payment_success. A declined one sends payment_failed. Both have the same shape as card webhooks, with paymentMethod set to Pay With Volume (the value production sends for pay-by-bank) and the customer’s bank in customer.billerId:

{
  "event_type": "payment_success",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "merchant": { "userId": "<your-accountId>" },
    "transaction": {
      "fee": 0.28,
      "type": "online_checkout",
      "transactionId": "WEB-ONLINE_C-abc123-9a7b3c1d-52e4-4f06-8b1a-xxxx",
      "merchantTxRef": "txref-1791194400",
      "transactionAmount": 50000.00,
      "time": "2026-10-05T10:00:00Z"
    },
    "customer": { "billerId": "Monzo", "productId": "" },
    "order": {
      "amount": 50000.00,
      "orderId": "a1b2c3d4-e5f6-47a8-xxxx-xxxxxxxxxxxx",
      "accountId": "<your-accountId>",
      "customerEmail": "[email protected]",
      "orderReference": "test-order-003",
      "paymentMethod": "Pay With Volume",
      "currency": "NGN"
    }
  }
}

{
  "event_type": "payment_failed",
  "requestId": "6f9619ff-8b86-d011-b42d-00c04fc964ff",
  "data": {
    "merchant": { "userId": "<your-accountId>" },
    "transaction": {
      "fee": 0.28,
      "type": "online_checkout",
      "transactionId": "WEB-ONLINE_C-abc123-1e2d3c4b-6a5f-4e7d-9c8b-xxxx",
      "merchantTxRef": "txref-1791194460",
      "transactionAmount": 50000.00,
      "time": "2026-10-05T10:01:00Z"
    },
    "customer": { "billerId": "Barclays", "productId": "" },
    "order": {
      "amount": 50000.00,
      "orderId": "a1b2c3d4-e5f6-47a8-xxxx-xxxxxxxxxxxx",
      "accountId": "<your-accountId>",
      "customerEmail": "[email protected]",
      "orderReference": "test-order-003",
      "paymentMethod": "Pay With Volume",
      "currency": "NGN"
    }
  }
}

Sandbox-only differences: there is no real bank redirect, transaction IDs and merchantTxRef are test values, and the fee is a fixed test amount.

Webhook payload

The sandbox fires webhooks synchronously immediately after a successful transaction — either after OTP approval (card) or confirm-transaction-receipt (bank transfer). Webhooks include HMAC-SHA256 signature headers for verification. Signature headers:

Header	Description
`nomba-signature`	HMAC-SHA256 signature of the payload
`nomba-sig-value`	Raw signature value
`nomba-signature-algorithm`	Always `HmacSHA256`
`nomba-timestamp`	ISO 8601 UTC timestamp of the event

Sample card payment webhook payload:

{
  "event_type": "payment_success",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "merchant": {
      "userId": "<your-accountId>"
    },
    "transaction": {
      "fee": 0.28,
      "type": "online_checkout",
      "transactionId": "WEB-ONLINE_C-abc123-550e4c3a-0af4-4887-a089-xxxx",
      "merchantTxRef": "txref-1743379200",
      "transactionAmount": 4000.00,
      "time": "2026-03-31T10:00:00Z"
    },
    "order": {
      "amount": 4000.00,
      "orderId": "a1b2c3d4-e5f6-47a8-xxxx-xxxxxxxxxxxx",
      "accountId": "<your-accountId>",
      "customerEmail": "[email protected]",
      "orderReference": "test-order-001",
      "paymentMethod": "card_payment",
      "currency": "NGN"
    }
  }
}

To receive webhooks during local development, use a tunnel tool (e.g. ngrok) to expose your local server and set the public URL as your callbackUrl when creating the order.

Refund testing

Refunds are available in the sandbox. Use POST /sandbox/checkout/refund with the transactionId from the fetch transaction response.

curl --request POST \
  --url https://sandbox.nomba.com/sandbox/checkout/refund \
  --header 'Authorization: Bearer <sandbox-token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <your-sandbox-accountId>' \
  --data '{
    "transactionId": "WEB-ONLINE_C-abc123-550e4c3a-...",
    "amount": 4000.00
  }'

To simulate a failed refund, use this specific transactionId:

WEB-ONLINE_C-97922-db88d4c3-a0af-4887-a089-b5d2e51b8f19

This always returns code: "400" regardless of the amount.

Simulating error states

What to test	How to trigger
Order not found	Use `orderReference: "1234567890"` — returns `404` on all endpoints
Card declined	Use card `5484497218317651`
Pay-by-bank declined	Select Decline payment on the test bank page
OTP timeout	Submit OTP `1234`
Invalid OTP	Submit OTP `5464`
Failed refund	Use transactionId `WEB-ONLINE_C-97922-db88d4c3-a0af-4887-a089-b5d2e51b8f19`
Failed tokenized card fetch	Use `customerEmail: "[email protected]"`

Next steps

Create a Checkout Order

Full field reference and production code examples

Verify Transactions

Confirm payment status before delivering value

Webhooks

Set up and verify webhook signatures

Environment

Understand sandbox vs production base URLs

Introduction

Getting Started

Products

API Basics

Guides

Before you start

Get your sandbox credentials

Generate a sandbox access token

Card payment flow

Step 1 — Create a checkout order

Step 2 — Submit card details

Test card numbers

Step 3 - Submit Card Pin (if required)

Step 4 — Submit OTP

Step 4 — Verify the transaction

International card flow

Step 1 — Create an order in USD, GBP or EUR

Step 2 — Pay with a test card

Step 3 — Verify the transaction

Webhooks

International pay-by-bank flow

Step 1 — Create an order

Step 2 — Choose a country and bank

Step 3 — Choose the outcome on the test bank page

Step 4 — Verify the transaction

Webhooks

Webhook payload

Refund testing

Simulating error states

Next steps

Create a Checkout Order

Verify Transactions

Webhooks

Environment

​Before you start

​Get your sandbox credentials

​Generate a sandbox access token

​Card payment flow

​Step 1 — Create a checkout order

​Step 2 — Submit card details

​Test card numbers

​Step 3 - Submit Card Pin (if required)

​Step 4 — Submit OTP

​Step 4 — Verify the transaction

​International card flow

​Step 1 — Create an order in USD, GBP or EUR

​Step 2 — Pay with a test card

​Step 3 — Verify the transaction

​Webhooks

​International pay-by-bank flow

​Step 1 — Create an order

​Step 2 — Choose a country and bank

​Step 3 — Choose the outcome on the test bank page

​Step 4 — Verify the transaction

​Webhooks

​Webhook payload

​Refund testing

​Simulating error states

​Next steps

Create a Checkout Order

Verify Transactions

Webhooks

Environment

Before you start

Get your sandbox credentials

Generate a sandbox access token

Card payment flow

Step 1 — Create a checkout order

Step 2 — Submit card details

Test card numbers

Step 3 - Submit Card Pin (if required)

Step 4 — Submit OTP

Step 4 — Verify the transaction

International card flow

Step 1 — Create an order in USD, GBP or EUR

Step 2 — Pay with a test card

Step 3 — Verify the transaction

Webhooks

International pay-by-bank flow

Step 1 — Create an order

Step 2 — Choose a country and bank

Step 3 — Choose the outcome on the test bank page

Step 4 — Verify the transaction

Webhooks

Webhook payload

Refund testing

Simulating error states

Next steps