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

# Request checkout page

> Request Beem's hosted checkout page. Set `sendSource=true` to receive a checkout URL in the response (recommended for backend redirects). Omit or set `sendSource=false` for an HTTP 302 redirect (recommended for frontend redirects).



## OpenAPI

````yaml /openapi/payments-checkout.json get /checkout
openapi: 3.0.3
info:
  title: Beem Payments Checkout API
  version: 1.0.0
  description: >-
    Bpay Checkout: request a hosted payment page, whitelist domains for iframe
    checkout, and receive payment status callbacks.
  contact:
    name: Beem
    url: https://beem.africa
    email: support@beem.africa
servers:
  - url: https://checkout.beem.africa/v1
    description: Bpay Checkout API
security: []
tags: []
paths:
  /checkout:
    get:
      summary: Request checkout page
      description: >-
        Request Beem's hosted checkout page. Set `sendSource=true` to receive a
        checkout URL in the response (recommended for backend redirects). Omit
        or set `sendSource=false` for an HTTP 302 redirect (recommended for
        frontend redirects).
      operationId: requestCheckoutPage
      parameters:
        - name: amount
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
            example: 1200
          description: Amount the customer must pay. Decimals are not allowed.
        - name: reference_number
          in: query
          required: true
          schema:
            type: string
            example: SAMPLE-12345
          description: >-
            Alphanumeric reference matching your route pattern (e.g.
            SAMPLE-12345).
        - name: transaction_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
            example: 96f9cc09-afa0-40cf-928a-d7e2b27b2408
          description: UUID v4 to track the payment.
        - name: mobile
          in: query
          required: false
          schema:
            type: string
            example: '255701000000'
          description: Customer mobile number with country code.
        - name: email
          in: query
          required: false
          schema:
            type: string
            format: email
          description: Customer email address.
        - name: currency
          in: query
          required: false
          schema:
            type: string
            default: TZS
            example: TZS
          description: ISO currency code. Defaults to TZS.
        - name: sendSource
          in: query
          required: false
          schema:
            type: boolean
            example: true
          description: >-
            When true, returns a checkout URL in JSON. When false or omitted,
            responds with HTTP 302 redirect.
        - name: beem-secure-token
          in: header
          required: false
          schema:
            type: string
          description: >-
            Optional client validation token. Sent back in the callback headers
            if provided.
      responses:
        '200':
          description: Checkout page URL when sendSource=true
          content:
            application/json:
              schema:
                type: object
                required:
                  - src
                properties:
                  src:
                    type: string
                    description: URL of the hosted checkout page.
              examples:
                redirectUrl:
                  summary: Checkout page URL (sendSource=true)
                  value:
                    src: >-
                      https://checkout.beem.africa/v1/checkout/page?token=8c6e3aac-498b-43b1-9074-34d222e55715
        '302':
          description: Redirect to checkout page when sendSource=false or omitted
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      code:
                        type: integer
                        description: API error code.
                      message:
                        type: string
                        description: Human-readable error message.
              examples:
                invalidTransactionId:
                  summary: Invalid transaction ID
                  value:
                    data:
                      code: 102
                      message: Invalid Transaction ID
        '401':
          description: Invalid authentication
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: API error code (120 = invalid authentication).
                  message:
                    type: string
                    description: Human-readable error message.
                  error:
                    type: string
                    description: Error detail when authorization header is missing.
              examples:
                invalidAuth:
                  summary: Invalid authentication
                  value:
                    code: 120
                    message: Invalid Authentication Parameters
                missingAuth:
                  summary: Missing authorization header
                  value:
                    error: No authorization headers
        '404':
          description: No payment method configured or invalid reference
          content:
            application/json:
              schema:
                type: object
                properties:
                  src:
                    type: string
                    description: URL of the checkout error page with an encoded message.
              examples:
                noPaymentMethod:
                  summary: No payment method configured
                  value:
                    src: >-
                      https://checkout.beem.africa/v1/checkout/error?message=No%20payment%20method%20set%20by%20client
      security:
        - basicAuth: []
        - accessToken: []
      servers:
        - url: https://checkout.beem.africa/v1
          description: Bpay Checkout API
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Beem API credentials: API key as username, API secret as password.'
    accessToken:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Access token only. Send as Authorization: <token> — do not use a Bearer
        prefix.

````