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

> Create the first order with tokenizeCard set to true so Nomba saves the customer's card.

<CardGroup cols={2}>
  <Card title="Create an online checkout order" icon="link-simple" href="/nomba-api-reference/online-checkout/create-an-online-checkout-order" />
</CardGroup>

**Step 1 of 7.** Before you can charge a card later, the customer has to pay with it once. Create a checkout order for that first payment, with `tokenizeCard` set to `true`.

The first payment does two things. It proves that the card is valid and can be charged, and the customer approves the payment with their bank. After that, you can charge the card without the customer re-entering their card details.

# `POST /v1/checkout/order`

<Warning>
  `tokenizeCard` goes at the **top level** of the request body, next to `order`. Nomba ignores it if you put it inside `order`, and the card isn't saved.
</Warning>

#### Headers

<ParamField header="Authorization" type="string" required>
  `Bearer <access_token>`. See [Authenticate](/docs/getting-started/authentication).
</ParamField>

<ParamField header="accountId" type="string" required>
  Your account ID
</ParamField>

#### Request body

These are the fields that matter for saving a card. For the full list, see [Create a checkout order](/docs/products/accept-payment/create-checkout-order).

<ParamField body="order" type="object" required>
  Details of the first payment

  <Expandable title="object" defaultOpen="true">
    <ParamField body="amount" type="string" required>
      The amount of the first payment, as a string with two decimal places, for example `"5000.00"`
    </ParamField>

    <ParamField body="currency" type="string" required>
      The currency code, for example `NGN`
    </ParamField>

    <ParamField body="customerEmail" type="string" required>
      The customer's email address. The card is saved against this email, and every later charge must use the same one.
    </ParamField>

    <ParamField body="orderReference" type="string">
      Your unique reference for this order, up to 50 characters. Nomba generates one if you leave it out.
    </ParamField>

    <ParamField body="customerId" type="string">
      Your own ID for the customer. Nomba returns it in the webhook, so you can match the card token to the customer.
    </ParamField>

    <ParamField body="callbackUrl" type="string">
      Where Nomba sends the customer after they pay on the checkout page
    </ParamField>

    <ParamField body="allowedPaymentMethods" type="string[]">
      Set it to `["Card"]`. Only a card payment can be saved, so if the customer pays by transfer, you won't get a card token.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tokenizeCard" type="boolean" required>
  Set it to `true` to save the card when the payment succeeds
</ParamField>

#### Response body

<ResponseField name="code" type="string" required>
  `"00"` when the order was created
</ResponseField>

<ResponseField name="description" type="string" required>
  Response description
</ResponseField>

<ResponseField name="status" type="boolean" required>
  Request status
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="object" defaultOpen="true">
    <ResponseField name="success" type="boolean" required>
      `true` when the order was created
    </ResponseField>

    <ResponseField name="message" type="string" required>
      Response message
    </ResponseField>

    <ResponseField name="checkoutLink" type="string" required>
      The link to the Nomba checkout page for this order
    </ResponseField>

    <ResponseField name="orderReference" type="string" required>
      Nomba's ID for the order, not the reference you sent. The webhook returns it as `order.orderId`.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Request theme={null}
  curl --request POST \
    --url https://api.nomba.com/v1/checkout/order \
    --header 'Authorization: Bearer <access_token>' \
    --header 'Content-Type: application/json' \
    --header 'accountId: <accountId>' \
    --data '{
      "order": {
        "orderReference": "sub-2026-10-0001",
        "customerId": "cus_48213",
        "customerEmail": "ada@example.com",
        "amount": "5000.00",
        "currency": "NGN",
        "callbackUrl": "https://example.com/payments/callback",
        "allowedPaymentMethods": ["Card"]
      },
      "tokenizeCard": true
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success response (200) theme={null}
  {
    "code": "00",
    "description": "checkout order created successful",
    "status": true,
    "data": {
      "success": true,
      "message": "Success",
      "checkoutLink": "https://pay.nomba.com/checkout/be727ded-aa6e-4b6e-beea-898d4428740a",
      "orderReference": "be727ded-aa6e-4b6e-beea-898d4428740a"
    }
  }
  ```
</ResponseExample>

Keep `data.orderReference` from the response. You send it with the card details in the next step.

## Choose the amount for the first payment

If the first payment is the customer's first bill, such as the first month of a subscription, charge the real amount.

If you only need the payment to save the card, charge a small amount. Then [refund it](/docs/products/accept-payment/refund-checkout-order), or give the customer the same value in your app, such as wallet credit. Nomba doesn't set a minimum amount, but some banks decline very small card payments, so test the amount you plan to use.

<Tip>
  Set `tokenizeCard` only when you plan to charge the card again. Tell the customer you'll save their card and how you'll use it, and get their agreement before they pay.
</Tip>

<Card title="Next: Submit card details" icon="arrow-right" href="/docs/products/accept-payment/recurring-payments/api/submit-card-details">
  Send the card details your customer entered on your page.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.