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

# Hosted pay page (HTML)

> What the QR opens. Optional `amount` (whole KES) prefills the amount for fixed-price QR codes.



## OpenAPI

````yaml /openapi.yaml get /pay/{code}
openapi: 3.1.0
info:
  title: CloudPay Core API
  version: 0.1.0
  summary: Wallet, ledger and payments API for CloudPay (Phase 0).
  description: >+
    cloudpay-core is the system of record for CloudPay e-money. Every shilling
    moves

    through a double-entry ledger that the database itself keeps balanced.


    ## Conventions

    - **Money** is always an integer number of **cents** (KES minor units).
    `150000` = KES 1,500.00.
      Never send decimals or floats.
    - **Phone numbers** accept `07XXXXXXXX`, `01XXXXXXXX`, `+2547XXXXXXXX` or
    `2547XXXXXXXX`
      and are returned as `2547XXXXXXXX`.
    - **Envelope**: every response is `{"status": {"ok", "code", "desc"},
    "data": ...}` on success
      and `{"status": ..., "errors": {"code", "message"}}` on failure. Branch on `errors.code`,
      which is stable; `message` is for humans.
    - **Tenancy**: unauthenticated endpoints name the tenant with `X-Tenant-ID`:
    its short slug
      (`cloudpay`) or UUID. Without the header they use the platform tenant (DEFAULT_TENANT_ID).
      Authenticated endpoints take the tenant from the token.
    - **Idempotency**: every money-moving request carries an `idempotency_key`
    (8-100 chars,
      unique per customer). Retrying with the same key and the same body returns the original
      result; the same key with a different body returns `409 idempotency_key_reused`.
    - **PIN step-up**: money leaving a wallet always needs the customer's PIN in
    the request,
      even with a valid token.

    ## Flows

    1. **Onboard**: `POST /v1/auth/otp` (purpose `register`) -> `POST
    /v1/auth/register`.

    2. **Login on a known device**: `POST /v1/auth/login` with PIN.
       **On a new device**: the first login returns `403 device_verification_required`;
       request an OTP with purpose `login`, then log in again with `otp`.
    3. **Top up from M-Pesa**: `POST /v1/topups/mpesa` sends an STK prompt and
    returns `pending`.
       The wallet is credited only after cloudpay-rails confirms. Poll `GET /v1/topups/{id}`
       until `completed`, `failed` or `review`.
    4. **Send money**: optionally `GET /v1/parties/lookup` to show the
    recipient's name, then
       `POST /v1/transfers`.

    ## Environments

    | Environment | Base URL | Money | M-Pesa | OTP |

    |---|---|---|---|---|

    | Production | `https://api.cloudpay.africa/cloudpay` | real | real
    (cloudpay-rails) | SMS |

    | Development (an `sk_test_` key or test session) |
    `https://api.cloudpay.africa/cloudpay` | real STK up to KES 100 per prompt
    and KES 1,000 per day, no payouts; carried to Production on approval |
    CloudPay platform rail | SMS never sent; `123456` accepted for any code you
    requested |

    | Local dev | `http://localhost:8080` | as above | provider sandboxes
    (cloudpay-rails) | `123456` for every tenant, plus `dev_code` in responses |


    There is one deployment: the key (`sk_test_` / `sk_live_`) and the tenant's
    mode choose the environment.


    Every response that resolves a tenant carries `X-CloudPay-Environment: live`
    or `test`, taken from the

    tenant. Check it in your client if you need to be sure which twin answered.
    Health endpoints omit it.


    **Development mode**

    - OTP `123456` is accepted for any OTP you requested, for test tenants.

    - M-Pesa prompts are real (STK to a handset you hold), collected through
    CloudPay's platform rail:
      up to KES 100 per prompt. Nothing is simulated by CloudPay. No payouts or settlements.
    - Payments are asynchronous: a new top-up, collection or disbursement is
    `initiated`, becomes
      `pending` once the provider accepts it (a Paystack checkout's `access_code` appears then), and
      ends `completed`, `failed` or `review`. Poll the GET endpoint.
    - Ready-made customers and merchants: the **Sandbox** endpoints below,
    authenticated with
      `Authorization: Bearer sk_test_...`. A live key gets 403 `live_mode_required`.

  contact:
    name: CloudPay Engineering
servers:
  - url: https://api.cloudpay.africa/cloudpay
    description: Production and Development (the key chooses)
  - url: http://localhost:8080
    description: Local dev (make dev / make up)
security:
  - bearer: []
tags:
  - name: Auth
    description: OTP, registration, login, PIN and sessions.
  - name: Wallet
    description: Profile, balance and statement.
  - name: Payments
    description: P2P transfers and M-Pesa top-ups.
  - name: Merchant pay
    description: >
      QR payments to merchants. A merchant QR encodes
      `{PUBLIC_BASE_URL}/pay/{code}`; scanning it

      opens a hosted page where the payer picks **M-Pesa** (STK prompt to any
      phone, no CloudPay

      account) or **CloudPay wallet** (sign in, confirm with PIN). Public
      endpoints resolve the

      tenant from the code; no X-Tenant-ID needed. `{code}` is a till's QR code
      (10 characters) or a

      pay-link (12 characters). A link that is disabled, expired or used up
      answers 403 `link_inactive`,

      `link_expired` or `link_used_up`.
  - name: Merchant API
    description: >
      Run a business: tills, members and roles, balances, statements, sweeps,
      API keys. Authenticate as a member

      (bearer session; the role decides) or with a merchant API key
      (`Authorization: Bearer sk_...` or `X-Api-Key`;

      its scopes decide). Permissions: read, collect, disburse, rails,
      credentials, links, transfer, settle,

      members, keys, settings.
  - name: Merchant webhooks
    description: >
      Get told when a collection or payout finishes instead of polling. Set one
      HTTPS endpoint; CloudPay POSTs a signed

      event for every final status (`collection.completed|failed|review`,
      `disbursement.completed|failed|review`) and

      retries for about 38 hours. Every attempt is kept (the trail). Also lists
      the CloudPay IPN addresses to paste

      into a provider dashboard when you use your own Paystack keys.
  - name: Merchant rails
    description: >
      Merchant & developer API for payment rails (M-Pesa, SasaPay, Paystack):
      choose rails, bring your own keys,

      collect, disburse, bulk. Authenticate with a merchant API key
      (`Authorization: Bearer sk_...`) or a member's

      session plus `X-Merchant-ID`. Permissions: `read`, `collect`, `disburse`,
      `rails`, `credentials`.
  - name: Sandbox
    description: >-
      Developer tooling for test tenants. Needs an `sk_test_` key; a live key
      gets 403 `live_mode_required`.
paths:
  /pay/{code}:
    get:
      tags:
        - Merchant pay
      summary: Hosted pay page (HTML)
      description: >-
        What the QR opens. Optional `amount` (whole KES) prefills the amount for
        fixed-price QR codes.
      operationId: payPage
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-z0-9]{10}$
        - name: amount
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 250000
      responses:
        '200':
          description: The page.
          content:
            text/html: {}
        '404':
          description: Unknown code (page explains it).
          content:
            text/html: {}
      security: []
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        `access_token` from register or login. Expires after JWT_TTL (default
        15m) or when the session ends.

````

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