> ## 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.

# Initiate a Direct Payment Request

> Send a payment request directly to a user's mobile device.

## Endpoint

`POST /direct-pay`

Send a payment request directly to a user's mobile device. You are responsible for building your own checkout and verifying payment status.

<Note>
  Direct payment transactions cannot and do not expire. Consequently, their final state is either **SUCCESSFUL** or **FAILED**.
</Note>

<Warning>
  Direct pay is disabled by default on live environment; Follow the steps in the
  [Activate Direct pay on your Live Fapshi API guide](https://www.fapshi.com/en/help-and-support/how-to-activate-direct-pay-for-your-fapshi-api)
  to enable direct pay in live mode.
</Warning>

<Danger>
  Handle this endpoint with care; misuse can result in account suspension.
</Danger>

## Parameters

| Name       | Required | Type    | Description                                                                  |
| :--------- | :------- | :------ | :--------------------------------------------------------------------------- |
| amount     | Yes      | integer | Amount to be paid (minimum 100 XAF).                                         |
| phone      | Yes      | string  | Phone number to request payment from (e.g., 67XXXXXXX).                      |
| medium     | No       | string  | `"mobile money"` or `"orange money"`. Omit to auto-detect.                   |
| name       | No       | string  | Payer’s name.                                                                |
| email      | No       | string  | Payer’s email to receive receipt.                                            |
| userId     | No       | string  | Your system’s 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
  * `transId`: transaction ID to track payment status
  * `dateInitiated`: date when the payment was initiated

* Errors return 4XX with failure message.


## OpenAPI

````yaml /en/api-reference/openapi.json POST /direct-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:
  /direct-pay:
    post:
      summary: Initiate a Direct Payment Request
      description: >-
        Send a payment request directly to a user's mobile device for
        confirmation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  minimum: 100
                  description: Amount to be paid (minimum 100 XAF).
                phone:
                  type: string
                  description: Phone number where payment request is sent.
                medium:
                  type: string
                  enum:
                    - mobile money
                    - orange money
                  description: Payment medium (optional).
                name:
                  type: string
                  description: Name of the payer (optional).
                email:
                  type: string
                  format: email
                  description: Email of the payer for receipts (optional).
                userId:
                  type: string
                  pattern: ^[a-zA-Z0-9\-_]{1,100}$
                  description: Internal user ID (optional).
                externalId:
                  type: string
                  pattern: ^[a-zA-Z0-9\-_]{1,100}$
                  description: Transaction/order ID for reconciliation (optional).
                message:
                  type: string
                  description: Reason for payment (optional).
              required:
                - amount
                - phone
      responses:
        '200':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
                  transId:
                    type: string
                    description: Transaction ID for the payment.
                  dateInitiated:
                    type: string
                    format: date
                    description: Date when the payment was initiated.
        4XX:
          description: Client error, e.g., invalid credentials 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

````