> ## Documentation Index > Fetch the complete documentation index at: https://developer.nomba.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a checkout order > Learn how to create a checkout order to accept payments Create an online checkout order to accept payments from your customers 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](/docs/getting-started/authentication). 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](/nomba-api-reference/online-checkout/create-an-online-checkout-order), 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](/nomba-api-reference/online-checkout/create-an-online-checkout-order) to this endpoint `/v1/checkout/order`. ```bash cURL theme={null} curl --request POST \ --url https://api.nomba.com/v1/checkout/order \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'accountId: ' \ --data '{ "order": { "amount": "10000.00", "currency": "NGN", "callbackUrl": "https://merchant.com/callback" } }' ``` ```javascript Node.js theme={null} const response = await fetch('https://api.nomba.com/v1/checkout/order', { method: 'POST', headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'accountId': accountId, }, body: JSON.stringify({ order: { amount: '10000.00', currency: 'NGN', callbackUrl: 'https://merchant.com/callback', customerEmail: 'customer@example.com', }, }), }); const { code, data } = await response.json(); if (code !== '00') throw new Error(`Checkout creation failed: ${code}`); // Redirect or display the checkout link to your customer const { checkoutLink, orderReference } = data; ``` ```python Python theme={null} import requests response = requests.post( 'https://api.nomba.com/v1/checkout/order', headers={ 'Authorization': f'Bearer {access_token}', 'Content-Type': 'application/json', 'accountId': account_id, }, json={ 'order': { 'amount': '10000.00', 'currency': 'NGN', 'callbackUrl': 'https://merchant.com/callback', 'customerEmail': 'customer@example.com', } }, ) result = response.json() if result['code'] != '00': raise Exception(f"Checkout creation failed: {result['code']} — {result['description']}") checkout_link = result['data']['checkoutLink'] order_reference = result['data']['orderReference'] ``` ```json Response theme={null} { "code": "00", "description": "Success", "data": { "checkoutLink": "https://checkout.nomba.com/pay/78388899***8", "orderReference": "90e81e8a-bc14-4ebf-89c0-57**********" } } ``` ```json Error Response theme={null} { "code": "02", "description": "amount can not be null", "data": null } ``` ## 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. Use `"NGN"` for Nigerian checkout. For DRC accounts, use `"CDF"` or `"USD"` — `"NGN"` is not supported for DRC and will be rejected. | | `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](#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. Pass `"region": "CD"` to route the order through DRC checkout (e.g. a Nigerian merchant accepting DRC MoMo payments). | | `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](https://nomba.com/contact) 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. **DRC accounts cannot use `NGN`.** If your account is registered in the DRC region, checkout orders must use `CDF` or `USD`. Sending `NGN` (or any other unsupported currency) from a DRC account will be rejected with a `400 Bad Request` error. This applies to both the dashboard and the API. ## 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](/docs/products/accept-payment/cancel-checkout-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](/docs/guides/managing-accounts-with-nomba#create-a-sub-account) 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**. ```json theme={null} "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 ```json theme={null} { "order": { "orderReference": "00000-bc14-4ebf-89c0-0003", "customerId": "221220251907", "callbackUrl": "https://new:port/merchant.com/callback", "customerEmail": "abcdef@gmail.com", "amount": "120.00", "currency": "NGN", "accountId": "01a10aeb-d989-460a-bbde-9**********", "allowedPaymentMethods": ["Card", "Transfer"] } } ``` ### DRC examples ```json DRC CDF theme={null} { "order": { "orderReference": "drc-cdf-order-001", "callbackUrl": "https://merchant.example.com/callback", "customerEmail": "customer@example.com", "amount": "120000.00", "currency": "CDF", "allowedPaymentMethods": ["MOMO"] } } ``` ```json DRC USD theme={null} { "order": { "orderReference": "drc-usd-order-001", "callbackUrl": "https://merchant.example.com/callback", "customerEmail": "customer@example.com", "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: ```json DRC USD With Multiple Methods theme={null} { "order": { "callbackUrl": "https://merchant.example.com/callback", "customerEmail": "customer@example.com", "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. ```json theme={null} "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 ```bash expandable theme={null} { 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: 'makurseme@gmail.com', 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](/docs/api-basics/webhook). ### Verify via API Check here to learn how to [verify transactions](/docs/products/accept-payment/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.