> ## Documentation Index
> Fetch the complete documentation index at: https://docs.afriex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Checkout Session

> Creates a hosted checkout session for a customer and returns a `checkoutUrl` that the customer should be redirected to in order to complete payment. The session captures the merchant intent (amount, currency, merchant reference, customer details, and allowed payment channels) and is identified end-to-end by the merchant-supplied `merchantReference`.

<Warning>
  **Coming soon.** Hosted checkout is not yet generally available in production, but you can already try it end-to-end in the **sandbox/staging** environment today. Use sandbox to call this endpoint, see how it works, and validate your integration while we finish the production rollout, which we expect to ship in the coming weeks.
</Warning>

Create a hosted checkout session for a customer. Afriex returns a `checkoutUrl` that you redirect the customer to so they can complete payment on Afriex's hosted page.

## How it works

1. Call this endpoint with the amount you want to collect, the customer's details, your `merchantReference`, and a `redirectUrl`.
2. Afriex returns a `checkoutUrl`.
3. Redirect the customer to that URL.
4. After payment, Afriex redirects the customer back to your `redirectUrl` and fires a `CHECKOUT_SESSION.CREATED` [webhook](/api-reference/endpoint/webhooks/introduction) to your configured callback URL.

## Identifying the session

The `merchantReference` you supply is the end-to-end identifier. Use it to look up the session, match webhook deliveries, and reconcile any resulting transaction in your system. It must be unique per session.

## Amounts are in minor units

`amount` is denominated in the smallest unit of the currency. For example, kobo for `NGN` or cents for `USD`. To charge ₦5,000.00, pass `500000`. Minimum value is `100` (one major unit).

## Restricting payment channels

Use `channels` to control which deposit rails the hosted page offers the customer. Supported values are `VIRTUAL_BANK_ACCOUNT`, `MOBILE_MONEY`, and `CARD`; pass at least one. For example, `["CARD", "MOBILE_MONEY"]` shows only the card and mobile-money options and hides the rest.

If you omit `channels`, the session defaults to `["VIRTUAL_BANK_ACCOUNT"]`.


## OpenAPI

````yaml POST /api/v1/checkout-session
openapi: 3.1.0
info:
  title: Afriex Business API
  version: 1.0.8
  description: >-
    Welcome to the Afriex Business API. This API allows you to manage customers,
    process payments, handle payouts, and receive real-time notifications via
    webhooks.


    For detailed guidance on authentication, pagination, error handling, and
    webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in
    the top bar. The guide provides a step-by-step instructions to help you
    integrate seamlessly.
  termsOfService: https://www.afriex.com/terms-and-condition
  contact:
    name: Afriex API Support
    email: eng@afriex.co
    url: https://docs.afriex.com
  license:
    name: Proprietary
    url: https://www.afriex.com/terms-and-condition
servers:
  - url: https://sandbox.api.afriex.com
    description: Staging Base URL
  - url: https://api.afriex.com
    description: Production Base URL
security:
  - ApiKey: []
tags:
  - name: Customers
    description: Create and manage your customers.
  - name: Payment Methods
    description: Register and resolve customer payout and collection methods.
  - name: Transactions
    description: Create and track deposits, withdrawals, and swaps.
  - name: Balance
    description: View and top up your business wallet balances.
  - name: Rates
    description: Fetch real-time exchange rates.
  - name: Checkout Sessions
    description: Create hosted checkout sessions.
  - name: Webhooks
    description: Webhook event payloads and sandbox webhook testing.
paths:
  /api/v1/checkout-session:
    parameters:
      - $ref: '#/components/parameters/x-api-version'
    post:
      tags:
        - Checkout Sessions
      summary: Create a checkout session
      description: >-
        Creates a hosted checkout session for a customer and returns a
        `checkoutUrl` that the customer should be redirected to in order to
        complete payment. The session captures the merchant intent (amount,
        currency, merchant reference, customer details, and allowed payment
        channels) and is identified end-to-end by the merchant-supplied
        `merchantReference`.
      operationId: createCheckoutSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - currency
                - merchantReference
                - redirectUrl
                - customer
              properties:
                amount:
                  type: integer
                  minimum: 100
                  description: >-
                    The transaction amount in **minor currency units** (e.g.
                    kobo for NGN, cents for USD). Minimum 100 (equivalent to 1
                    major currency unit).
                  examples:
                    - 500000
                currency:
                  type: string
                  description: >-
                    Uppercase 3-letter ISO 4217 currency code (e.g. NGN, GHS).
                    Must be a currency enabled for checkout sessions on the
                    business.
                  examples:
                    - NGN
                merchantReference:
                  type: string
                  minLength: 1
                  description: >-
                    Unique merchant-supplied reference for this session. Used
                    end-to-end to look up the session and any resulting
                    transaction.
                  examples:
                    - order-2026-05-12-001
                redirectUrl:
                  type: string
                  format: uri
                  description: >-
                    HTTPS URL the customer is redirected to after the hosted
                    checkout flow completes.
                  examples:
                    - https://merchant.example.com/checkout/return
                customer:
                  $ref: '#/components/schemas/CheckoutSessionCustomer'
                channels:
                  type: array
                  minItems: 1
                  description: >-
                    Payment channels the customer is allowed to use for this
                    session. Defaults to `[VIRTUAL_BANK_ACCOUNT]` if omitted.
                  items:
                    type: string
                    enum:
                      - VIRTUAL_BANK_ACCOUNT
                      - MOBILE_MONEY
                      - CARD
                  default:
                    - VIRTUAL_BANK_ACCOUNT
                metadata:
                  type: object
                  maxProperties: 50
                  description: >-
                    Optional flat key/value metadata to attach to the session.
                    Both keys and values must be strings. At most 50 entries;
                    keys up to 128 characters, values up to 1024 characters.
                  additionalProperties:
                    type: string
                    maxLength: 1024
            examples:
              minimal:
                summary: Minimal checkout session
                value:
                  amount: 500000
                  currency: NGN
                  merchantReference: order-2026-05-12-001
                  redirectUrl: https://merchant.example.com/checkout/return
                  customer:
                    name: John Doe
                    email: john.doe@example.com
                    phone: '+2348192837465'
                    countryCode: NG
              withChannelsAndMetadata:
                summary: With explicit channels and metadata
                value:
                  amount: 500000
                  currency: NGN
                  merchantReference: order-2026-05-12-002
                  redirectUrl: https://merchant.example.com/checkout/return
                  customer:
                    name: John Doe
                    email: john.doe@example.com
                    phone: '+2348192837465'
                    countryCode: NG
                  channels:
                    - VIRTUAL_BANK_ACCOUNT
                    - CARD
                  metadata:
                    orderId: '12345'
                    source: web
      responses:
        '201':
          description: Checkout session created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CreateCheckoutSessionResponse'
              examples:
                created:
                  summary: Session created
                  value:
                    data:
                      checkoutUrl: >-
                        https://checkout.afriex.com/pay/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid business API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: TypeScript
          label: Afriex SDK
          source: |
            const session = await afriex.checkout.createSession({
              amount: 500000,
              currency: "NGN",
              merchantReference: "order-2026-05-12-001",
              redirectUrl: "https://yourapp.com/checkout/return",
              customer: {
                name: "John Doe",
                email: "john@example.com",
                phone: "+2348192837465",
                countryCode: "NG",
              },
              channels: ["VIRTUAL_BANK_ACCOUNT"],
              metadata: { orderId: "order-456", cartId: "cart-123" },
            });

            // Redirect customer to session.checkoutUrl
            console.log(session.checkoutUrl);
components:
  parameters:
    x-api-version:
      name: x-api-version
      in: header
      required: false
      description: >-
        API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest
        stable.
      schema:
        type: string
  schemas:
    CheckoutSessionCustomer:
      type: object
      required:
        - name
        - email
        - phone
        - countryCode
      properties:
        name:
          type: string
          description: The full name of the customer.
          examples:
            - John Doe
        email:
          type: string
          format: email
          description: The email address of the customer.
          examples:
            - john.doe@example.com
        phone:
          type: string
          description: The phone number of the customer in E.164 format.
          examples:
            - '+2348192837465'
        countryCode:
          type: string
          description: >-
            The ISO 3166-1 alpha-2 country code of the customer (e.g., 'NG',
            'GH'). Case-insensitive; values are normalized to uppercase.
          examples:
            - NG
    CreateCheckoutSessionResponse:
      type: object
      properties:
        checkoutUrl:
          type: string
          format: uri
          description: >-
            The URL the customer should be redirected to in order to complete
            the hosted checkout flow.
          examples:
            - https://checkout.afriex.com/pay/eyJhbGciOiJI...
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
        error:
          type: string
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ErrorDetails'
    ErrorDetails:
      type: object
      properties:
        errorMessage:
          type: string
          description: Detailed/technical error message.
        friendlyMessage:
          type: string
          description: User-facing error message safe to display.
        data:
          type: object
          description: >-
            Optional caller-safe context for the error. On a customer-create
            uniqueness conflict (EMAIL_ALREADY_EXISTS /
            PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's
            id, so you can adopt it without a follow-up lookup.
          properties:
            customerId:
              type: string
              description: Id of the existing customer (on a create conflict).
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Static business API key issued from the dashboard. A business can
        provision **multiple API keys**, each scoped to a configurable set of
        **permissions** (e.g. read transactions, create deposits, etc).
        Permissions are chosen per key at creation time in the dashboard and may
        be revoked by deleting the key. Requests made with a key that does not
        include the permission required by the target endpoint will be rejected
        with a `403 Forbidden` response; an unrecognised, malformed or revoked
        key returns `401 Unauthorized`. Manage your keys and their permissions
        under **Developer → API keys** in the dashboard.

````