Skip to main content

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.

This guide walks you through the full integration journey. For a detailed field reference, code examples, and advanced features, see the Create Checkout Order product page.

​
Introduction

Nomba Checkout is a hosted payment page that lets your customers pay via bank transfer or debit card (Mastercard, Visa, Verve). You create an order via API, hand your customer the checkout link, and Nomba handles the payment flow — including card authentication, OTP, and 3DS.

​
Integration steps

1

Get your API keys

Before making any API call, retrieve your credentials from the Nomba dashboard. You’ll need your clientId, clientSecret, and accountId.Both sandbox (test) and production credentials are available. Use sandbox credentials with https://sandbox.nomba.com during development. See Environment for base URL details.
2

Configure your webhook

Nomba notifies your server of payment events via webhooks. Set up your webhook endpoint in the dashboard and subscribe to the payment_success event before you go live.See the Webhook guide for setup instructions and payload verification.
3

Authenticate

Exchange your credentials for an access token. All subsequent API calls require this token in the Authorization header.
curl --request POST \
    --url https://api.nomba.com/v1/auth/token/issue \
    --header 'Content-Type: application/json' \
    --header 'accountId: <accountid>' \
    --data '{
      "grant_type": "client_credentials",
      "client_id": "<your-clientId>",
      "client_secret": "<your-clientSecret>"
    }'
Response
{
    "code": "00",
    "description": "Success",
    "data": {
        "access_token": "eyJhbGci...",
        "refresh_token": "01h4gdx2...",
        "expiresAt": "2026-01-01T14:33:00Z"
    }
}
4

Create a checkout order

Call POST /v1/checkout/order with the payment amount and customer details. Nomba returns a checkoutLink — display or redirect your customer to this URL to complete payment.
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": "your-unique-order-ref",
        "amount": "10000.00",
        "currency": "NGN",
        "customerEmail": "[email protected]",
        "callbackUrl": "https://merchant.com/callback"
      }
    }'
Response
{
    "code": "00",
    "description": "Success",
    "data": {
        "checkoutLink": "https://checkout.nomba.com/pay/xxxxxxxxxx",
        "orderReference": "your-unique-order-ref"
    }
}
Pick the checkoutLink from the response and load it in a browser or iframe to let your customer pay.
For the full list of request fields (split payments, tokenization, allowed payment methods), see Create Checkout Order.
5

Handle the webhook

Once payment is successful, Nomba sends a payment_success webhook to your configured URL. The payload differs slightly between card and bank transfer payments.Card payment webhook:
{
    "event_type": "payment_success",
    "requestId": "ddfadc29-d1c0-41d6-904d-a71a6740f1c4",
    "data": {
        "transaction": {
            "transactionId": "WEB-ONLINE_C-CB677-27b33599-9359-4aa3-b4d0-9c60f3b4a978",
            "type": "online_checkout",
            "transactionAmount": 2400.0,
            "fee": 93.6,
            "time": "2024-01-11T16:33:04Z"
        },
        "order": {
            "orderReference": "your-unique-order-ref",
            "amount": 2400.0,
            "currency": "NGN",
            "paymentMethod": "card_payment",
            "cardType": "Visa",
            "cardLast4Digits": "8038"
        }
    }
}
Bank transfer webhook:
{
    "event_type": "payment_success",
    "requestId": "a8b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6",
    "data": {
        "transaction": {
            "transactionId": "WEB-ONLINE_C-CB677-83a1b2c3-d4e5-6f7a-b8c9-0d1e2f3a4b56",
            "type": "online_checkout",
            "transactionAmount": 2400.0,
            "fee": 93.6,
            "time": "2024-01-11T16:40:12Z"
        },
        "customer": {
            "billerId": "8022636522",
            "senderName": "John Doe"
        },
        "order": {
            "orderReference": "your-unique-order-ref",
            "amount": 2400.0,
            "currency": "NGN",
            "paymentMethod": "bank_transfer"
        }
    }
}
See the Webhook guide for signature verification instructions.
6

Verify the transaction

Always verify the transaction server-side before delivering goods or services. Do not rely on the webhook alone.Use the transactionId from the webhook (data.transaction.transactionId) to call GET /v1/transactions/accounts/single:
curl --request GET \
    --url 'https://api.nomba.com/v1/transactions/accounts/single?transactionRef=WEB-ONLINE_C-CB677-27b33599-9359-4aa3-b4d0-9c60f3b4a978' \
    --header 'Authorization: Bearer <token>' \
    --header 'accountId: <accountid>'
Check that data.status is "SUCCESS" before proceeding.
You can also verify using the orderReference as a query param instead of transactionRef. See Verify Transactions for full details.

​
Next steps

Checkout Overview

See all checkout features and quick links

Sandbox Testing

Test your integration with sandbox credentials and test cards

Recurring Payments

Charge saved cards for subscriptions and recurring billing

Refund a Transaction

Process refunds for completed payments