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. Customers can make payments with their Mastercard, Visa or Verve cards; when they do, Nomba sends a payment receipt to the customer email provided when you created the order. 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 tokenizedCard 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": {
      "orderReference": "90e81e8a-bc14-4ebf-89c0-57**********",
      "customerId": "762878332454",
      "callbackUrl": "https://ip:port/merchant.com/callback",
      "customerEmail": "[email protected]",
      "amount": "10000.00",
      "currency": "NGN",
      "accountId": "01a10aeb-d989-460a-bbde-9**********",
      "splitRequest": {
        "splitType": "PERCENTAGE",
        "splitList": [
          {
            "accountId": "01a10aeb-d989-460a-bbde-98**********",
            "value": "65.45"
          }
        ]
      }
    },
    "tokenizeCard": "true"
  }'

​
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"
    }
  ]
}

​
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:
  • 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.