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

# Make a Payout

> Send money to a user's mobile money, orange money or fapshi account via a payout-enabled service.

## Endpoint

`POST /payout`

Send money to a user's mobile money, orange money or fapshi account via a payout-enabled service.

<Danger>After enabling payouts for a service, that service can no longer collect payments. Use separate services for collections and payouts.</Danger>

<Warning>
  Payout is disabled by default in the live environment. To activate payouts in live environment, first implement and test payouts in sandbox environment, then send an email to Developer Support at [support.fapshi.com](mailto:support.fapshi.com) with your <strong>Live API User ONLY</strong> and mention that you want to enable payouts on your service.

  MAKE SURE YOU SEND <strong>THE LIVE API USER</strong> of your <strong>PAYOUT SERVICE</strong>.
</Warning>

## Parameters

| Name       | Required    | Type    | Description                                                                                                                                                     |
| :--------- | :---------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount     | Yes         | integer | Amount to send (minimum 100 XAF).                                                                                                                               |
| phone      | Conditional | string  | Recipient phone number (e.g., 67XXXXXXX). Required when `medium` is not specified or not `"fapshi"`.                                                            |
| medium     | No          | string  | `"mobile money"`, `"orange money"`, or `"fapshi"`. Auto-detected if omitted (requires `phone`). When set to `"fapshi"`, `email` is required instead of `phone`. |
| name       | No          | string  | Recipient's name.                                                                                                                                               |
| email      | Conditional | string  | Recipient's email. Required when `medium` is `"fapshi"`. Optional for payout confirmation receipt when `medium` is not `"fapshi"`.                              |
| userId     | No          | string  | Your system's user ID for payout tracking (1-100 chars; allowed: a-z, A-Z, 0-9, -, \_).                                                                         |
| externalId | No          | string  | Transaction/order ID for reconciliation (1-100 chars; allowed: a-z, A-Z, 0-9, -, \_).                                                                           |
| message    | No          | string  | Description or reason for payout.                                                                                                                               |

### Required Fields

* **When `medium` is not specified**: `amount` and `phone` are required.
* **When `medium` is `"fapshi"`**: `amount` and `email` are required.

### Sandbox Testing

When testing payouts with `medium` set to `"fapshi"` in the sandbox environment:

* **Emails that always return successful transactions**: `test.success@fapshi.com` and `messi.champion@fapshi.com`
* **Emails that always return failed transactions**: `test.failed@fapshi.com` and `penaldo.test@fapshi.com`
* **Other emails**: Transaction status will be determined in a stochastic (random) manner


## OpenAPI

````yaml /en/api-reference/openapi.json POST /payout
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:
  /payout:
    post:
      summary: Make a Payout
      description: >-
        Send money to a user's mobile money, orange money or fapshi account via
        a payout-enabled service. When `medium` is not specified, `amount` and
        `phone` are required. When `medium` is set to `"fapshi"`, `amount` and
        `email` are required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  minimum: 100
                  description: Amount to send (minimum 100 XAF).
                phone:
                  type: string
                  description: >-
                    Recipient phone number. Required when `medium` is not
                    specified or not `"fapshi"`. Not required when `medium` is
                    `"fapshi"`.
                medium:
                  type: string
                  enum:
                    - mobile money
                    - orange money
                    - fapshi
                  description: >-
                    Payment medium (optional). Auto-detected if omitted
                    (requires `phone`). When set to `"fapshi"`, `email` is
                    required instead of `phone`.
                name:
                  type: string
                  description: Recipient name (optional).
                email:
                  type: string
                  format: email
                  description: >-
                    Recipient email. Required when `medium` is `"fapshi"`.
                    Optional for payout receipt when `medium` is not `"fapshi"`.
                userId:
                  type: string
                  pattern: ^[a-zA-Z0-9\-_]{1,100}$
                  description: User ID for payout tracking (optional).
                externalId:
                  type: string
                  pattern: ^[a-zA-Z0-9\-_]{1,100}$
                  description: Transaction/order ID for reconciliation (optional).
                message:
                  type: string
                  description: Reason for payout (optional).
              required:
                - amount
      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: Invalid request or insufficient permissions
          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

````