The FedaPay API allows you to easily integrate secure payment solutions into your website or application. This guide will walk you through the process of setting up and managing payment collects using the API, from the initial creation to the finalization, including advanced features such as redirection-free payments. Whether you are a developer or a product manager, you’ll find everything you need to optimally use FedaPay.

​
Steps to Create and Manage a Payment Collect

The steps to set up a collect are broken down into several key processes.

1

Collect Initialization: Creating a Request

The first step is to send a request to create a collect via the API. This request requires certain mandatory parameters:

  • description: A brief description of the collect’s purpose

  • amount: The amount, always in whole numbers

  • currency: The currency, indicated by its ISO code or number (refer to the FedaPay Currency Table for details)

  • callback_url: An optional link to redirect the customer after payment

  • customer: The customer related to the collect

If the customer is not yet registered in your system, you can create their profile by adding details such as name, email, and phone number.

​
Example query to create a collects

  curl -X POST \
  https://sandbox-api.fedapay.com/v1/transactions \
  -H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
  -H 'Content-Type: application/json' \
  -d '{
        "description" : "Transaction for john.doe@example.com",
        "amount" : 2000,
        "currency" : {"iso" : "XOF"},
        "callback_url" : "https://maplateforme.com/callback",
        "customer" : {
            "firstname" : "John",
            "lastname" : "Doe",
            "email" : "john.doe@example.com",
            "phone_number" : {
                "number" : "+22997808080",
                "country" : "bj"
            }
          }
      }'

Find more information in our API Reference

Replace YOUR_SECRETE_API_KEY with your API key and use the URL of the appropriate server (sandbox or live).

If the customer is already registered, simply use their ID or email to associate them with the collect.

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

Generate Token and Payment Link

After sending the request, the API will return a unique identifier for the collect. Use this ID to request a payment link and token, which will redirect the customer to a secure payment page.

curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions/ID/token \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json'

The generated link can be used to redirect users to FedaPay’s secure payment page.

3

Redirect to Payment Page

This link redirects your customer to a secure payment page where they can complete the collect. If you’ve specified a callback_url, the customer will automatically be redirected once the payment is complete.

4

Using the Return Link (Callback URL)

The callback_url is used to redirect the customer to a specific page after the payment, with the status and collect ID as parameters. For example:

  • Payment approved : https://www.monsite.com/?id=258&status=approved

  • Payment canceled : https://www.monsite.com/?id=259&status=canceled

Note: For security reasons, do not rely solely on the status provided in the URL. Always perform a direct check with the API to get the actual status.

5

Retrieve Collect Details

To retrieve complete information for a collect, you can send a request using its collection ID.

​
Example query to retrieve details of a collects

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

curl -X GET \
https://sandbox-api.fedapay.com/v1/transactions/ID \
-H 'Authorization: Bearer YOUR_SECRETE_API_KEY' \
-H 'Content-Type: application/json'
Find more information in our API Reference

​
Payments Without Redirection

To provide a smooth experience without redirection, you can directly integrate the payment form into your application for specific methods (MTN Benin, Moov Benin, Moov Togo, and MTN Côte d’Ivoire). This payment mode is especially useful for e-commerce sites that want to keep users on their platform throughout the process, without redirecting them to another page.

Sending a Mobile Payment Without Redirection

The mobile payment process without redirection is divided into two main steps in either the Live or Sandbox environment:

1

Create a Payment Collection

The first step is to create a collection via the FedaPay API. This generates a token required to complete the transaction.

2

Trigger the Payment

Once you have the payment token, you need to send a request to the FedaPay API to process the payment. The request is made using one of the specific payment methods

Here is an example code to send a mobile payment without redirection

curl -X POST \
https://sandbox-api.fedapay.com/v1/METHODE_PAIEMENT \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json'
-d '{
  "token" : "TOKEN_DE_PAIEMENT",
  "phone_number": {
    "number": "64000001",
    "country":"bj"
  }
}'

Important Notes :

Replace METHODE_PAIEMENT with the chosen payment method (e.g., mtn_benin, moov_benin, etc.).

VOTRE_CLE_API_SECRETE must be replaced with your secret API key (in sandbox mode for testing or live mode for production transactions).

When you’re ready to go live, replace the sandbox URL with the Live URL :

  • Sandbox : https://sandbox-api.fedapay.com

  • Live : https://api.fedapay.com/v1/transactions/ID

Important: Make sure to thoroughly test your integrations in the sandbox environment before deploying them to production.

Note:

The phone_number parameter is not mandatory for the payment notification request. However, if it is not specified, FedaPay will try to send the notification to the number linked to the customer associated with the transaction when it was created.

Note: Payments without redirection do not support all operators. Refer to the Payment Methods section for more details on supported methods.

​
Automatic Retrieval of Collect Status

To check the final status of a collection, especially during redirection-free payments:

​
Collect Lifecycle: Statuses

Each collection passes through various statuses:

  • pending : Pending (default status upon creation)

  • approved : Approved (successful payment)

  • declined : Declined (voluntary or accidental interruption by the customer)

  • canceled : Canceled (insufficient funds or other payment issues)

  • refunded : Refunded (amount reversed to the customer)

  • transferred : Transferred (amount moved to the merchant account)

To view the real-time status, visit the FedaPay dashboard under the Collects section or use the API to check using the collect ID.