A payout is an operation that allows you to transfer money directly from your balance to a customer’s account. This feature is designed for businesses that need to handle payments to specific clients.

​
Steps to Create a Payout

Creating a payout through the API involves several steps. Each payout follows processes that must be respected to ensure smooth transfer.
1

Payout Creation Request

To begin, you need to send a request to create a payout via our API. The essential information required in the request includes:
  • amount : The amount for the payout, always in whole numbers.
  • currency : The currency to be used for the payout. You can indicate the ISO code of the chosen currency (e.g., XOF for CFA francs).
  • customer : The customer receiving the payout. If the customer is not yet in your database, you can create them at the same time by providing details such as name, email, and phone number.

​
Example of a request for creating a repository

  curl -X POST \
  https://sandbox-api.fedapay.com/v1/payouts \
  -H 'Authorization: Bearer VOTRE_CLE_API_PRIVEE' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount" : 2000,
        "currency" : {"iso" : "XOF"},
        "mode": "mtn_open" 
        "customer" : {
            "firstname" : "John",
            "lastname" : "Doe",
            "email" : "john.doe@example.com",
            "phone_number" : {
                "number" : "+22997808080",
                "country" : "bj"
            }
        }
      }'
Find more information in our API ReferenceSample code is available to simplify the creation of a repository via the API. Be sure to replace YOUR_SECRETE_API_KEY with your sandbox or live private key.
Note:The customer parameter is not mandatory. However, when creating a transaction with a customer, make sure that the email address is unique. FedaPay considers it to be the same customer if the emails are identical. If you send the same email address but enter different first and last names and phone numbers, FedaPay will simply update the customer with the new information.
2

Sending the Payout

Once a payout has been created, it will be marked as pending. You then need to proceed with sending the payout. Two options are available:
  • Send the payout immediately.
  • Schedule the payout for later. 
    curl -X PUT \
https://sandbox-api.fedapay.com/v1/payouts/start \
-H 'Authorization: Bearer VOTRE_CLE_API_PRIVEE' \
-H 'Content-Type: application/json'
-d '{
    "payouts" : [
      { "id": 23 }, // Sends the deposit instantly
      { "id": 23, "phone_number": { "number": "66000001", "country": "BJ" } }, // Sends deposit instantly with phone number
      { "id": 24 , "scheduled_at": "2024-11-18 18:8:43"} // Send payout later
    ]
  }'
3

Retrieve Payout Details

After creating and/or sending the payout, you can view its details to obtain specific information, such as status or payout history.

​
Example query to retrieve payout details


/*Replace YOUR_API_SECRET_KEY by the API secret key of your sandbox or live account. If you are using your live account, you must replace the link by https://api.fedapay.com/v1/payouts/ID   */

  curl -X GET \
  https://sandbox-api.fedapay.com/v1/payouts/ID \
  -H 'Authorization: Bearer YOUR_API_SECRET_KEY' \
  -H 'Content-Type: application/json'
Find more information in our API ReferenceRetrieve information on a specific repository using its unique identifier (ID). Replace ID in the URL with the ID of the repository you wish to consult.

​
Payout Lifecycle

When a payout is created, it moves through several statuses:
  • pending : Pending (initial status after payout creation).
  • started : The payout has been validated and is in the process of being initiated.
  • processing : The payout is being processed and sent to the recipient.
  • sent : The payout has been successfully sent to the recipient.
  • failed : The payout failed due to issues such as technical error or method-related problems.
You can track the status of your payouts from the FedaPay dashboard under the Payouts section.

​
Available Payout Methods

Currently, the available payout methods for sending funds to different countries in West Africa are supported These methods make it easy to send money to various countries in the region.

​
Add Custom Metadata to Your Payouts

When initiating a payout from your FedaPay balance to a Mobile Money account (MTN Benin, MTN Côte d’Ivoire, Moov Benin, Moov Togo, or Togocel), you can attach custom metadata to the operation using the custom_metadata field. This allows you to enrich each payout with useful business-related information, such as a user ID, a transfer purpose, a service reference, or any data specific to your system. Why Use custom_metadata in a Payout? The custom_metadata field is particularly helpful for:
  • Keeping a clear and structured trace of each transaction within your platform.
  • Automating internal processes by linking payouts to users, orders, or events.
  • Simplifying audits and reconciliation with metadata stored directly in the transaction.
  • Saving time by avoiding manual cross-referencing between FedaPay IDs and your own records.
Example: Perform a Payout with Custom Metadata Here’s a sample API request to send a payout with attached metadata:
Curl
curl -X POST https://sandbox-api.fedapay.com/v1/payouts \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json' \
-d '{
  "amount": 3000,
  "currency": {"iso": "XOF"},
  "description": "Paiement de commission d’un agent",
  "receiver": {
    "name": "Koffi Kodjo",
    "phone_number": "+22961234567",
    "provider": "mtn"
  },
  "custom_metadata": {
    "agent_id": "AGT-0032",
    "mois": "Juillet",
    "type": "commission"
  }
}'
Good to Know
  • The custom_metadata field accepts a JSON object with key-value pairs.
  • Use simple and meaningful keys like type, month, client_id.
  • This field is optional, but strongly recommended for better data management and traceability.
  • Avoid including sensitive or confidential information, such as passwords or card details.

​
Support

If you have any questions or encounter difficulties with payouts, feel free to contact our support team at: support@fedapay.com