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

# Hosted checkout

> Create a fixed-amount payment link and read its payment status.

Create a single-payment invoice priced in USD. Hosted checkout supports card, Sarafa, and KES/UGX mobile payments. Link creation itself does not move funds or produce a payment callback.

```json theme={null}
{
  "amount": "25",
  "currency": "USD",
  "title": "Order 100",
  "description": "Payment for your order",
  "reference": "order-100",
  "callback_url": "https://merchant.example/payments",
  "redirect_url": "https://merchant.example/orders/100"
}
```

`redirect_url` is optional. It must use HTTPS without embedded credentials. All other fields above are required. Checkout creation does not accept a `quote` field.

Example response, HTTP `201`:

```json theme={null}
{
  "status": "success",
  "checkout": {
    "slug": "<generated-slug>",
    "title": "Order 100",
    "description": "Payment for your order",
    "amount": "25",
    "currency": "USD",
    "status": "open",
    "created_at": "2026-10-30T10:00:00.000Z",
    "reference": "order-100",
    "checkout_url": "https://checkout.sarafa.site/p/<generated-slug>",
    "transactions": []
  }
}
```

Redirect the payer to the returned `checkout_url`. Successful payment closes the link to further payments; failed attempts can be retried. Each attempt has its own `tx_reference` while retaining your checkout reference.

## Check checkout status

Use your merchant reference with `GET /v3/checkout/{reference}`:

```bash theme={null}
curl "https://api.sarafa.site/v3/checkout/order-100" \
  -H "Authorization: Bearer $SARAFA_API_KEY"
```

Returns HTTP `200` with the same checkout response shape, including associated transactions. An unknown checkout reference within your organization returns HTTP `404`.

| Checkout status | Meaning |
| - | - |
| `open` | Available for payment. |
| `paid` | Successfully paid; further payments are closed. |
| `closed` | Closed without a successful payment. |

Browser redirects are not proof of payment. Confirm the outcome using this authenticated status read, [payment details](https://docs.sarafa.ss/api-reference/endpoint/getTransaction.md), or [signed callbacks](https://docs.sarafa.ss/services/api.md).


## OpenAPI

````yaml api-reference/openapi.json POST /checkout
openapi: 3.0.3
info:
  title: Sarafa Business API
  version: 3.0.0
  description: >-
    Server-side access to your verified organization's account. Use Bearer API
    keys, decimal-string amounts, and unique merchant references. Charge,
    transfer, and swap default to quotes. Only transaction.status = completed
    confirms payment.
servers:
  - url: https://api.sarafa.site/v3
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Accounts
  - name: Transactions
  - name: Payments
  - name: Checkout
paths:
  /checkout:
    post:
      tags:
        - Checkout
      summary: Create hosted checkout
      description: >-
        Create a fixed-amount, single-payment USD invoice. Supports card,
        Sarafa, and KES/UGX mobile payments. Returns the same link on an
        identical retry. Does not accept quote.
      operationId: createCheckout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
            example:
              amount: '25'
              currency: USD
              title: Order 100
              description: Payment for your order
              reference: order-100
              callback_url: https://merchant.example/payments
              redirect_url: https://merchant.example/orders/100
      responses:
        '201':
          description: Created checkout, or an identical replay.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
              example:
                status: success
                checkout:
                  slug: <generated-slug>
                  title: Order 100
                  description: Payment for your order
                  amount: '25'
                  currency: USD
                  status: open
                  created_at: '2026-10-30T10:00:00.000Z'
                  reference: order-100
                  checkout_url: https://checkout.sarafa.site/p/<generated-slug>
                  transactions: []
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '500':
          $ref: '#/components/responses/Error500'
        '503':
          $ref: '#/components/responses/Error503'
components:
  schemas:
    CheckoutRequest:
      type: object
      required:
        - amount
        - currency
        - title
        - description
        - reference
        - callback_url
      properties:
        amount:
          type: string
          pattern: ^[0-9]+([.][0-9]{1,18})?$
          description: >-
            Positive decimal string, not a JSON number. Zero is invalid.
            Currency-specific precision and payment limits also apply.
          example: '100.00'
        currency:
          type: string
          enum:
            - USD
        title:
          type: string
          minLength: 1
          maxLength: 160
        description:
          type: string
          minLength: 1
        reference:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Your idempotency reference, unique across charge, transfer, swap,
            and checkout creation within your organization. Reuse it with
            unchanged details for execution retries.
        callback_url:
          type: string
          format: uri
          pattern: ^https://
          description: >-
            HTTPS URL without embedded credentials. Required even for quotes.
            Receives signed payment callbacks.
          example: https://merchant.example/payments
        redirect_url:
          type: string
          format: uri
          pattern: ^https://
          description: >-
            Optional browser return URL. Must use HTTPS without embedded
            credentials. Redirects are not proof of payment.
      additionalProperties: false
    CheckoutResponse:
      type: object
      required:
        - status
        - checkout
      properties:
        status:
          type: string
          enum:
            - success
        checkout:
          $ref: '#/components/schemas/Checkout'
    Checkout:
      type: object
      required:
        - slug
        - title
        - description
        - amount
        - currency
        - status
        - created_at
        - reference
        - checkout_url
        - transactions
      properties:
        slug:
          type: string
        title:
          type: string
        description:
          type: string
        amount:
          type: string
          description: Decimal string.
        currency:
          type: string
          enum:
            - USD
        status:
          type: string
          enum:
            - open
            - paid
            - closed
        created_at:
          type: string
          format: date-time
        reference:
          type: string
        checkout_url:
          type: string
          format: uri
          description: Redirect the payer to this URL.
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/TransactionSummary'
          description: >-
            Payment attempts, newest first. Read a transaction by tx_reference
            for its currency, quote, and approval details.
    Error:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum:
            - failed
        error:
          type: string
        request_id:
          type: string
          description: >-
            Present on processing errors. Every response also includes
            X-Request-Id.
        issues:
          type: array
          items:
            type: object
            required:
              - path
              - message
            properties:
              path:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
              message:
                type: string
    TransactionSummary:
      type: object
      required:
        - tx_reference
        - transaction_type
        - product
        - description
        - amount
        - total_amount
        - total_fees
        - channel
        - status
        - created_at
        - updated_at
      properties:
        tx_reference:
          type: string
          description: >-
            Sarafa payment reference. Newly generated references are 13
            characters; existing longer references remain valid.
          example: TX7A2B9C4D1E0
        transaction_type:
          type: string
          enum:
            - credit
            - debit
        product:
          type: string
        description:
          type: string
        amount:
          type: string
          description: Decimal string.
        total_amount:
          type: string
          description: Decimal string.
        total_fees:
          type: string
          description: Decimal string.
        channel:
          type: string
        status:
          type: string
          description: >-
            Payment state. Only completed confirms payment; pending and
            needs_review are not final. Failed approvals can include a rejection
            or expiry reason.
          example: pending
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  headers:
    RequestId:
      description: Include this request identifier when contacting support.
      schema:
        type: string
  responses:
    Error400:
      description: >-
        Invalid JSON, fields, amount, precision, or currency/channel
        combination.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error401:
      description: Missing, invalid, inactive, or revoked API key.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error403:
      description: Required verification or authorization missing.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: Resource not found within your organization.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error409:
      description: >-
        Conflicting reference, insufficient balance, changed quote, or
        payment-state conflict.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error500:
      description: >-
        Processing failure. Retry uncertain executions with the same reference
        and unchanged payload.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error503:
      description: >-
        Service failure. Retry uncertain executions with the same reference and
        unchanged payload.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sfb_live_<public_identifier>.<secret>
      description: >-
        Use the full key from the merchant dashboard API section. Keep it on
        your server.

````

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