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



## OpenAPI

````yaml /openapi/payments.yaml get /pay/{shortCode}
openapi: 3.0.3
info:
  title: Simiz Payments API
  version: 2024-01
  description: >
    The Simiz Payments API lets you accept Mobile Money payments in Central and
    West Africa.


    ## Authentication


    All payment endpoints require a Bearer token using your API key:


    ```

    Authorization: Bearer smz_test_sk_xxx

    ```


    Checkout **public** endpoints (retrieve, pay, status, cancel) require no
    authentication — they are accessed by the end customer.


    ## Environments


    | Environment | Base URL | API Key Prefix |

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

    | **Sandbox** | `https://sandbox.api.simiz.io/v1` | `smz_test_` |

    | **Production** | `https://api.simiz.io/v1` | `smz_live_` |


    ## Idempotency


    For `POST` requests, include an `Idempotency-Key` header to safely retry
    requests without creating duplicate resources. Keys expire after 24 hours.
  contact:
    name: Simiz Support
    email: developer@simiz.io
    url: https://simiz.io/docs
  license:
    name: Proprietary
    url: https://simiz.io/legal/terms
servers:
  - url: https://api.simiz.io/v1
    description: Production — use smz_live_ keys
  - url: https://sandbox.api.simiz.io/v1
    description: Sandbox — use smz_test_ keys
security: []
tags:
  - name: Payments
    description: >
      Create and manage payment transactions. A transaction represents a single
      payment from a customer via Mobile Money. Authenticated with API key.
  - name: Checkout (Public)
    description: >
      Public checkout endpoints used by the payment page on the customer side.
      No authentication required.
  - name: Payment Links (Public)
    description: >
      Public payment link resolution. These endpoints are used by the hosted
      payment page when a customer opens a payment link. **No authentication
      required.**
paths:
  /pay/{shortCode}:
    get:
      tags:
        - Payment Links (Public)
      summary: Get payment link by short code
      description: >
        Retrieve a payment link by its short code. Returns the link details
        along with merchant information.

        Used by the hosted payment page when a customer opens a payment link.
        **No authentication required.**
      operationId: getPaymentLink
      parameters:
        - name: shortCode
          in: path
          required: true
          description: 8-character alphanumeric short code
          schema:
            type: string
            example: Ab12Cd34
      responses:
        '200':
          description: Payment link details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
              example:
                id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                shortCode: Ab12Cd34
                url: https://pay.simiz.io/pay/Ab12Cd34
                name: Monthly Invoice
                description: Pay your monthly invoice
                amount: 5000
                currency: XAF
                minAmount: null
                maxAmount: null
                status: ACTIVE
                collectPhone: true
                collectEmail: true
                collectName: false
                customFields: []
                maxUses: null
                usageCount: 12
                expiresAt: null
                createdAt: '2024-01-15T10:30:00Z'
                updatedAt: '2024-01-15T10:30:00Z'
                merchantName: My Store
                merchantLogo: https://cdn.simiz.io/logos/store.png
                projectId: 550e8400-e29b-41d4-a716-446655440000
        '404':
          $ref: '#/components/responses/NotFound'
      security: []
components:
  schemas:
    PaymentLink:
      type: object
      properties:
        id:
          type: string
          format: uuid
        shortCode:
          type: string
          description: 8-character alphanumeric code used in the URL
          example: Ab12Cd34
        url:
          type: string
          format: uri
          description: Full payment link URL
          example: https://pay.simiz.io/pay/Ab12Cd34
        name:
          type: string
          description: Link name / title
          example: Monthly Invoice
        description:
          type: string
          nullable: true
          description: Optional description shown to the customer
        amount:
          type: number
          nullable: true
          description: >-
            Fixed amount in smallest currency unit, or null for variable-amount
            links
          example: 5000
        currency:
          type: string
          description: ISO 4217 currency code
          example: XAF
        minAmount:
          type: number
          nullable: true
          description: Minimum amount for variable-amount links
        maxAmount:
          type: number
          nullable: true
          description: Maximum amount for variable-amount links
        status:
          $ref: '#/components/schemas/PaymentLinkStatus'
        collectPhone:
          type: boolean
          description: Whether the customer is asked for their phone number
        collectEmail:
          type: boolean
          description: Whether the customer is asked for their email
        collectName:
          type: boolean
          description: Whether the customer is asked for their full name
        customFields:
          type: array
          items:
            type: object
          description: Custom fields to collect from the customer
        maxUses:
          type: integer
          nullable: true
          description: Maximum number of uses allowed, or null for unlimited
        usageCount:
          type: integer
          description: Current number of times this link has been used
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: Expiration date, or null if the link does not expire
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        merchantName:
          type: string
          description: Organization name (only included on public endpoint)
        merchantLogo:
          type: string
          nullable: true
          description: Organization logo URL (only included on public endpoint)
        projectId:
          type: string
          format: uuid
          description: Project UUID (only included on public endpoint)
    PaymentLinkStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - EXPIRED
      description: |
        Payment link lifecycle:
        - `ACTIVE` — Link is live and accepting payments
        - `INACTIVE` — Link is disabled by the merchant
        - `EXPIRED` — Link has passed its expiration date
    ApiError:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            statusCode: 404
            message: Payment not found
            error: Not Found

````