curl --request POST \
  --url https://api.nomba.com/v1/checkout/order \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountId>' \
  --data '{
    "order": {
      "orderReference": "sub-2026-10-0001",
      "customerId": "cus_48213",
      "customerEmail": "[email protected]",
      "amount": "5000.00",
      "currency": "NGN",
      "callbackUrl": "https://example.com/payments/callback",
      "allowedPaymentMethods": ["Card"]
    },
    "tokenizeCard": true
  }'

{
  "code": "00",
  "description": "checkout order created successful",
  "status": true,
  "data": {
    "success": true,
    "message": "Success",
    "checkoutLink": "https://pay.nomba.com/checkout/be727ded-aa6e-4b6e-beea-898d4428740a",
    "orderReference": "be727ded-aa6e-4b6e-beea-898d4428740a"
  }
}

curl --request POST \
  --url https://api.nomba.com/v1/checkout/order \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountId>' \
  --data '{
    "order": {
      "orderReference": "sub-2026-10-0001",
      "customerId": "cus_48213",
      "customerEmail": "[email protected]",
      "amount": "5000.00",
      "currency": "NGN",
      "callbackUrl": "https://example.com/payments/callback",
      "allowedPaymentMethods": ["Card"]
    },
    "tokenizeCard": true
  }'

{
  "code": "00",
  "description": "checkout order created successful",
  "status": true,
  "data": {
    "success": true,
    "message": "Success",
    "checkoutLink": "https://pay.nomba.com/checkout/be727ded-aa6e-4b6e-beea-898d4428740a",
    "orderReference": "be727ded-aa6e-4b6e-beea-898d4428740a"
  }
}

Create an online checkout order

Step 1 of 5. Before you can charge a card later, the customer has to pay with it once. Create a checkout order for that first payment, with tokenizeCard set to true. The first payment does two things. It proves that the card is valid and can be charged, and the customer approves the payment with their bank. After that, you can charge the card without the customer re-entering their card details.

`POST /v1/checkout/order`

tokenizeCard goes at the top level of the request body, next to order. Nomba ignores it if you put it inside order, and the card isn’t saved.

Headers

string

required

Bearer <access_token>. See Authenticate.

string

required

Your account ID

Request body

These are the fields that matter for saving a card. For the full list, see Create a checkout order.

object

required

Details of the first payment

Hide object

string

required

The amount of the first payment, as a string with two decimal places, for example "5000.00"

string

required

The currency code, for example NGN

string

required

The customer’s email address. The card is saved against this email, and every later charge must use the same one.

string

Your unique reference for this order, up to 50 characters. Nomba generates one if you leave it out.

string

Your own ID for the customer. Nomba returns it in the webhook, so you can match the card token to the customer.

string

Where Nomba sends the customer after they pay on the checkout page

string[]

Set it to ["Card"]. Only a card payment can be saved, so if the customer pays by transfer, you won’t get a card token.

boolean

required

Set it to true to save the card when the payment succeeds

Response body

string

required

"00" when the order was created

string

required

Response description

boolean

required

Request status

object

required

Hide object

boolean

required

true when the order was created

string

required

Response message

string

required

The link to the Nomba checkout page for this order

string

required

Nomba’s ID for the order, not the reference you sent. The webhook returns it as order.orderId.

curl --request POST \
  --url https://api.nomba.com/v1/checkout/order \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountId>' \
  --data '{
    "order": {
      "orderReference": "sub-2026-10-0001",
      "customerId": "cus_48213",
      "customerEmail": "[email protected]",
      "amount": "5000.00",
      "currency": "NGN",
      "callbackUrl": "https://example.com/payments/callback",
      "allowedPaymentMethods": ["Card"]
    },
    "tokenizeCard": true
  }'

{
  "code": "00",
  "description": "checkout order created successful",
  "status": true,
  "data": {
    "success": true,
    "message": "Success",
    "checkoutLink": "https://pay.nomba.com/checkout/be727ded-aa6e-4b6e-beea-898d4428740a",
    "orderReference": "be727ded-aa6e-4b6e-beea-898d4428740a"
  }
}

Send the customer to checkout

Redirect the customer to the checkoutLink, or open it in a web view in your app. The customer enters their card details and completes any checks their bank asks for, such as an OTP. When the payment succeeds, Nomba saves the card. You don’t need to make any more API calls.

Choose the amount for the first payment

If the first payment is the customer’s first bill, such as the first month of a subscription, charge the real amount. If you only need the payment to save the card, charge a small amount. Then refund it, or give the customer the same value in your app, such as wallet credit. Nomba doesn’t set a minimum amount, but some banks decline very small card payments, so test the amount you plan to use.

Set tokenizeCard only when you plan to charge the card again. Tell the customer you’ll save their card and how you’ll use it, and get their agreement before they pay.

Next: Get and store the card token

Read the token from the webhook and save it with your customer.

Introduction

Getting Started

Products

API Basics

Guides

Create a checkout order

Create an online checkout order

`POST /v1/checkout/order`

Headers

Request body

Response body

Send the customer to checkout

Choose the amount for the first payment

Next: Get and store the card token

Create an online checkout order

​POST /v1/checkout/order

​Headers

​Request body

​Response body

​Send the customer to checkout

​Choose the amount for the first payment

Next: Get and store the card token

`POST /v1/checkout/order`

Headers

Request body

Response body

Send the customer to checkout

Choose the amount for the first payment