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

<Danger>
  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.
</Danger>

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

<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

````

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