> ## 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.

# Accept online payments

> End-to-end guide for integrating Nomba Checkout to accept online payments.

<Note>
  This guide walks you through the full integration journey. For a detailed field reference, code examples, and advanced features, see the [Create Checkout Order](/docs/products/accept-payment/create-checkout-order) product page.
</Note>

## 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.

<Frame caption="Accept online payments">
  <img src="https://mintcdn.com/nombainc/VJp6uGRaVI4ms-qk/images/accept-online-payment-guide-1.png?fit=max&auto=format&n=VJp6uGRaVI4ms-qk&q=85&s=131e89303c3462c94120c442538191de" style={{ borderRadius: '0.5rem' }} loading="lazy" width="2000" height="1802" data-path="images/accept-online-payment-guide-1.png" />
</Frame>

## Integration steps

<Steps>
  <Step title="Get your API keys">
    Before making any API call, retrieve your credentials from the [Nomba dashboard](https://dashboard.nomba.com). 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](/docs/api-basics/environment) for base URL details.
  </Step>

  <Step title="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](/docs/api-basics/webhook) for setup instructions and payload verification.
  </Step>

  <Step title="Authenticate">
    Exchange your credentials for an access token. All subsequent API calls require this token in the `Authorization` header.

    ```bash theme={null}
    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>"
        }'
    ```

    ```json Response theme={null}
    {
        "code": "00",
        "description": "Success",
        "data": {
            "access_token": "eyJhbGci...",
            "refresh_token": "01h4gdx2...",
            "expiresAt": "2026-01-01T14:33:00Z"
        }
    }
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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": "customer@example.com",
            "callbackUrl": "https://merchant.com/callback"
          }
        }'
    ```

    ```json Response theme={null}
    {
        "code": "00",
        "description": "Success",
        "data": {
            "checkoutLink": "https://checkout.nomba.com/pay/xxxxxxxxxx",
            "orderReference": "your-unique-order-ref"
        }
    }
    ```

    <Tip>
      Pick the `checkoutLink` from the response and load it in a browser or iframe to let your customer pay.
    </Tip>

    For the full list of request fields (split payments, tokenization, allowed payment methods), see [Create Checkout Order](/docs/products/accept-payment/create-checkout-order).
  </Step>

  <Step title="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:**

    ```json theme={null}
    {
        "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:**

    ```json theme={null}
    {
        "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](/docs/api-basics/webhook) for signature verification instructions.
  </Step>

  <Step title="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`:

    ```bash theme={null}
    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.

    <Tip>
      You can also verify using the `orderReference` as a query param instead of `transactionRef`. See [Verify Transactions](/docs/products/accept-payment/verify-transactions) for full details.
    </Tip>
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Checkout Overview" icon="house" href="/docs/products/accept-payment/checkout-overview">
    See all checkout features and quick links
  </Card>

  <Card title="Sandbox Testing" icon="flask" href="/docs/products/accept-payment/sandbox-testing">
    Test your integration with sandbox credentials and test cards
  </Card>

  <Card title="Recurring Payments" icon="arrows-rotate" href="/docs/products/accept-payment/recurring-payments">
    Charge saved cards for subscriptions and recurring billing
  </Card>

  <Card title="Refund a Transaction" icon="rotate-left" href="/docs/products/accept-payment/refund-checkout-order">
    Process refunds for completed payments
  </Card>
</CardGroup>