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 Reference

Sample 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

const { FedaPay, Payout } = require('fedapay');
/* Replace YOUR_SECRETE_API_KEY with your real API key */
FedaPay.setApiKey("YOUR_SECRETE_API_KEY");
/* Specify whether you want to run your query in test or live mode */
FedaPay.setEnvironment('sandbox'); //or setEnvironment('live');
/* Show a payout */
const payout = await Payout.retrieve(params = {}, headers = {});

Find more information in our API Reference

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

​
Support

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