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

# Generate a Payment Link

> Create a payment link to redirect users to a Fapshi-hosted checkout page.

## Endpoint

`POST /initiate-pay`

Generate a payment link where users complete payment on a prebuilt Fapshi checkout page.

## Parameters

| Name        | Required | Type    | Description                                                                  |
| :---------- | :------- | :------ | :--------------------------------------------------------------------------- |
| amount      | Yes      | integer | Amount to be paid (minimum 100 XAF).                                         |
| email       | No       | string  | If set, the user won't have to provide an email during payment.              |
| redirectUrl | No       | string  | URL to redirect the user after payment.                                      |
| userId      | No       | string  | Your internal user ID (1-100 chars; a-z, A-Z, 0-9, -, \_).                   |
| externalId  | No       | string  | Transaction/order ID for reconciliation (1-100 chars; a-z, A-Z, 0-9, -, \_). |
| message     | No       | string  | Reason for payment.                                                          |

## Response

* `200 OK` with JSON body containing:
  * `message`: success message
  * `link`: URL for user payment
  * `transId`: transaction ID to track payment status
  * `dateInitiated`: date when the payment was initiated

* Errors return 4XX with a message explaining the failure.

<Note>Payment links expire after 24 hours and cannot be used afterward.</Note>


## OpenAPI

````yaml /en/api-reference/openapi.json POST /initiate-pay
openapi: 3.1.0
info:
  title: Fapshi Payment API
  description: >-
    API for generating payment links, direct payments, transaction monitoring,
    payouts, and more.
  version: 1.0.0
servers:
  - url: https://sandbox.fapshi.com
security:
  - apiAuth: []
    apiKey: []
paths:
  /initiate-pay:
    post:
      summary: Generate a Payment Link
      description: >-
        Create a payment link where users complete payment on a Fapshi-hosted
        checkout page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  minimum: 100
                  description: Amount to be paid (minimum 100 XAF).
                email:
                  type: string
                  format: email
                  description: Optional user email to skip during payment.
                redirectUrl:
                  type: string
                  format: uri
                  description: URL to redirect after payment.
                userId:
                  type: string
                  pattern: ^[a-zA-Z0-9\-_]{1,100}$
                  description: Internal user ID (1-100 chars; a-z, A-Z, 0-9, -, _).
                externalId:
                  type: string
                  pattern: ^[a-zA-Z0-9\-_]{1,100}$
                  description: >-
                    Transaction/order ID for reconciliation (1-100 chars; a-z,
                    A-Z, 0-9, -, _).
                message:
                  type: string
                  description: Reason for payment.
              required:
                - amount
      responses:
        '200':
          description: Payment link generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
                  link:
                    type: string
                    format: uri
                    description: URL to redirect the user to complete payment.
                  transId:
                    type: string
                    description: Transaction ID for payment.
                  dateInitiated:
                    type: string
                    format: date
                    description: Date when the payment was initiated.
        4XX:
          description: Client error, e.g., invalid request or parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message.
  securitySchemes:
    apiAuth:
      type: apiKey
      in: header
      name: apiuser
    apiKey:
      type: apiKey
      in: header
      name: apikey

````