Create a checkout order

Create an online checkout order to accept payments from your customers

Charge Tokenized card

Charge customer tokenize card with a token key.

Create a checkout order

To create a checkout order, you need to authenticate with Nomba to get your access token. If you don’t know how to do this, see the getting started section to learn how to obtain API keys and obtain access tokens. Checkout supports different payment methods based on your account, region, currency, and enabled checkout configuration. To generate a checkout order link, make a POST call to /checkout/order. The Nomba API responds with a success message containing the checkout link, which your app will display to the customer for them to make payment. Here are a few things to take note of when creating a checkout order.

Kindly be aware that the optional boolean value tokenizeCard should be included or set to true only if you intend to tokenize your customer’s card for the purpose of attempting card payments at a later time.
Please pass the accountId inside the order request object if you wish to generate a checkout link for a subaccount.
Include the splitRequest parameter in the order object if you intend to split your payment.

Account ID: if specified in the order object, this is the account where the funds will be deposited. Also, this has to be one of your outlet accounts with Nomba. This will enable you to process checkout transactions for different subaccounts.

You can create a subaccount from the dashboard; follow this guide to learn how to create a subaccount and obtain your subaccount account ID. You will also learn how to follow our settlement cycle to set up auto settlement to external banks via subaccount. To create a checkout, send a POST request to this endpoint /v1/checkout/order.

  curl --request POST \
    --url https://api.nomba.com/v1/checkout/order \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --header 'accountId: <accountid>' \
    --data '{
    "order": {
      "amount": "10000.00",
      "currency": "NGN",
      "callbackUrl": "https://merchant.com/callback"
    }
  }'

Request Fields

Top-level fields

Field	Type	Required	Description
`order`	object	Yes	The order object. See fields below.
`tokenizeCard`	boolean	No	Set to `true` to save the customer’s card for future charges. Returns a `tokenKey` in the webhook payload on successful payment.
`meta`	object	No	Arbitrary key-value metadata attached to the order. Not used for payment processing.

`order` object fields

Field	Type	Required	Description
`amount`	string	Yes	The order amount as a string (e.g. `"10000.00"`).
`currency`	string	Yes	ISO 4217 currency code. For Nigerian checkout use `"NGN"`.
`orderReference`	string	No	A unique identifier you assign to this order. If omitted, Nomba generates one and returns it in the response. Must be unique per merchant — reusing a reference may result in an error. Recommended format: UUID v4.
`callbackUrl`	string	No	The URL Nomba redirects the customer to after payment is completed or abandoned. Nomba appends the `orderReference` as a query parameter. Must be a valid HTTPS URL.
`customerEmail`	string	No	Customer’s email address. Nomba sends a payment receipt to this address on successful payment. Must be a valid email format.
`customerId`	string	No	Your internal identifier for the customer. Stored on the order and returned in webhooks.
`accountId`	string	No	The Nomba sub-account ID to credit for this order. If omitted, the authenticated parent account is credited.
`splitRequest`	object	No	Split payment configuration. See Split payment section.
`orderMetaData`	object	No	Arbitrary key-value metadata to attach to the order. Both keys and values must be strings (e.g. `{"productName": "Premium Plan", "internalRef": "INV-001"}`). Stored on the order and returned in webhook payloads.
`allowedPaymentMethods`	array	No	List of payment methods to display on the checkout page. If omitted, all available methods are shown.

The orderReference in the response is the same value you passed in the request. If you did not provide one, the orderReference in the response is the Nomba-generated reference — use this for all downstream calls (verification, cancellation, etc.).

Supported Currencies

Currency	Code	Availability
Nigerian Naira	`NGN`	Available to all merchants by default
Congolese Franc	`CDF`	Available for supported DRC checkout flows
US Dollar	`USD`	Activated on demand
Euro	`EUR`	Activated on demand
British Pound	`GBP`	Activated on demand

NGN is the default currency and requires no additional setup. CDF is available for supported DRC checkout flows. To accept payments in USD, EUR, or GBP, your account must be enabled for foreign currency checkout. Nomba screens merchants and activates these currencies only after the required compliance obligations are met. To request foreign currency activation, contact Nomba support or reach out to your account manager.

Passing a currency that has not been activated on your account will result in an error. Always confirm your enabled currencies before going live with multi-currency checkout.

Checkout Link Lifecycle

After creating an order, Nomba returns a checkoutLink. Display or redirect your customer to this URL to complete payment.

The link remains active until the customer completes payment or the order is explicitly cancelled via Cancel Order.
After a successful or failed payment, Nomba redirects the customer to your callbackUrl (if provided).
The orderReference is appended as a query parameter on redirect, e.g. https://merchant.com/callback?orderReference=90e81e8a-....
Nomba also sends a payment_success webhook event to your configured webhook URL upon successful payment.

Split payment

The Checkout service allows you to distribute a single payment across multiple accounts. You can define how the order value is shared either as a percentage of the total or as a fixed amount. This is useful when you want to receive inflows in a separate account for a product you are collecting payment for. For example, if you are selling a product for ₦1,000 and 10% of the price is your profit, you may want to separate the profit from the original amount. In this case, you can create a sub-account on the Nomba dashboard, pass the sub-account ID, and set the percentage to 10%. This means that every transaction from checkout will automatically deposit ₦100 into the sub-account. See this guide to learn how to create a sub-account on Nomba dashboard. To enable this feature, include the optional splitRequest parameter when creating the checkout order.

Use splitType: “PERCENTAGE” to specify shares as percentages of the order value.
Use splitType: “AMOUNT” to specify exact amounts.

If you choose to cover the transaction fee, it will always be deducted from your primary account.

"splitRequest": {
  "splitType": "PERCENTAGE",
  "splitList": [
    {
      "accountId": "01a10aeb-d989-460a-bbde-9**********",
      "value": "65.45"
    },
    {
      "accountId": "02c20beb-a123-460a-bbde-9**********",
      "value": "34.55"
    }
  ]
}

Allowed Payment Methods

You can control which payment methods are displayed to customers on the checkout page by specifying the optional allowedPaymentMethods field in the order object. This field accepts a list of payment methods that should be available during checkout. Supported values include:

Card
Transfer
Nomba QR
USSD
Buy Now Pay Later
MOMO
Intl Card
Apple Pay

If allowedPaymentMethods is not provided, all enabled payment methods on your account will be displayed. Payment-method availability is region-aware and configuration-aware. For example:

Supported DRC CDF checkout flows can expose MOMO
Supported DRC USD checkout flows can expose MOMO, Intl Card, and Apple Pay
Nigerian checkout flows can continue to expose methods such as Card, Transfer, USSD, Nomba QR, and other enabled local methods

For Vendor API integrations, the authenticated account region determines the applicable checkout configuration. Currency alone should not be treated as the business-region source of truth. For DRC collections specifically, Checkout supports:

MOMO for both CDF and USD collections
Apple Pay for supported USD collections
Intl Card for supported USD collections

Example

{
  "order": {
    "orderReference": "00000-bc14-4ebf-89c0-0003",
    "customerId": "221220251907",
    "callbackUrl": "https://new:port/merchant.com/callback",
    "customerEmail": "[email protected]",
    "amount": "120.00",
    "currency": "NGN",
    "accountId": "01a10aeb-d989-460a-bbde-9**********",
    "allowedPaymentMethods": ["Card", "Transfer"]
  }
}

DRC examples

DRC CDF

{
  "order": {
    "orderReference": "drc-cdf-order-001",
    "callbackUrl": "https://merchant.example.com/callback",
    "customerEmail": "[email protected]",
    "amount": "120000.00",
    "currency": "CDF",
    "allowedPaymentMethods": ["MOMO"]
  }
}

DRC USD

{
  "order": {
    "orderReference": "drc-usd-order-001",
    "callbackUrl": "https://merchant.example.com/callback",
    "customerEmail": "[email protected]",
    "amount": "25.00",
    "currency": "USD",
    "allowedPaymentMethods": ["MOMO", "Intl Card", "Apple Pay"]
  }
}

You can also create a DRC USD checkout order with all three supported methods enabled:

DRC USD With Multiple Methods

{
  "order": {
    "callbackUrl": "https://merchant.example.com/callback",
    "customerEmail": "[email protected]",
    "amount": "100.98",
    "currency": "USD",
    "orderReference": "90e81e8a-bc14-4ebf-89c0-57da752ccb65",
    "customerId": "customer1234",
    "accountId": "08a1b86d-9140-4967-9998-29114a9e9421",
    "allowedPaymentMethods": ["MOMO", "Apple Pay", "Intl Card"]
  },
  "tokenizeCard": true
}

Tokenize Card

If you need to support recurring or subscription payments, set the optional parameter tokenizeCard to true when creating the order. Include and set the tokenizeCard field to true.

"tokenizeCard": true

When the payment is successfully completed, Nomba will send a webhook with the event type payment_success. This webhook includes a tokenizedCardData object containing the tokenKey and other card details. You should save the tokenKey, as it is required to charge the card for future recurring payments.

Sample Webhook Payload

{
  event_type: 'payment_success',
  requestId: '1ef33774-6d95-411c-b5*************',
  data: {
    merchant: {
      walletId: '1ef33774-6d95-411c-b5*************',
      walletBalance: 259.47,
      userId: '1ef33774-6d95-411c-b5*************'
    },
    terminal: {},
    tokenizedCardData: {
      tokenKey: 'N/A',
      cardType: 'Visa',
      tokenExpiryYear: 'N/A',
      tokenExpiryMonth: 'N/A',
      cardPan: '4***45**** ****111*'
    },
    transaction: {
      fee: 2.8,
      type: 'online_checkout',
      transactionId: 'WEB-ONLINE_C-69923-2e102708-ee34-4a29-b713-a826ca928a********',
      cardIssuer: 'Visa',
      responseCode: '',
      originatingFrom: 'web',
      merchantTxRef: '18********',
      transactionAmount: 202.8,
      time: '2025-09-11T11:50:05Z'
    },
    customer: { billerId: '418745**** ****1119', productId: '418***' },
    order: {
      amount: 202.8,
      orderId: '1ef33774-6d95-411c-b5*************',
      cardType: 'Visa',
      accountId: '1ef33774-6d95-411c-b5*************',
      cardLast4Digits: '111*',
      cardCurrency: 'NGN',
      customerEmail: '[email protected]',
      customerId: '7628783*******',
      isTokenizedCardPayment: 'false',
      orderReference: '1ef33774-6d95-411c-b5*************',
      paymentMethod: 'card_payment',
      callbackUrl: 'https://nomba.com',
      currency: 'NGN'
    }
  }
}

Verify Transaction

After receiving the webhook notification, always verify the transaction with Nomba before giving value to your customer. This ensures that the event is genuine and the payment was truly successful. You can verify transactions in two ways:

Webhook Validation (Recommended)

Compute the webhook hash sent in the request headers.
Compare it against your own generated hash to confirm the integrity of the payload.
Learn how to compute webhook signatures in the Webhook guide.

Verify via API

Check here to learn how to verify transactions. The API responds with the transaction details and status.

While webhooks notify you in real time, it is best practice to always verify all transactions with the Nomba API before delivering goods or services.

Introduction

Getting Started

Products

API Basics

Guides

Create a checkout order

Create a checkout order

Charge Tokenized card

Create a checkout order

Request Fields

Top-level fields

`order` object fields

Supported Currencies

Checkout Link Lifecycle

Split payment

Allowed Payment Methods

Example

DRC examples

Tokenize Card

Sample Webhook Payload

Verify Transaction

Webhook Validation (Recommended)

Verify via API

Introduction

Getting Started

Products

API Basics

Guides

Create a checkout order

Charge Tokenized card

​Create a checkout order

​Request Fields

​Top-level fields

​order object fields

​Supported Currencies

​Checkout Link Lifecycle

​Split payment

​Allowed Payment Methods

​Example

​DRC examples

​Tokenize Card

​Sample Webhook Payload

​Verify Transaction

​Webhook Validation (Recommended)

​Verify via API

Create a checkout order

Request Fields

Top-level fields

`order` object fields

Supported Currencies

Checkout Link Lifecycle

Split payment

Allowed Payment Methods

Example

DRC examples

Tokenize Card

Sample Webhook Payload

Verify Transaction

Webhook Validation (Recommended)

Verify via API