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 ReferenceReplace 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)
  • expired : Expired (the collect was not completed within the allowed time frame)
To view the real-time status, visit the FedaPay dashboard under the Collects section or use the API to check using the collect ID.

​
Add Custom Data to Your FedaPay Transactions: merchant_reference and custom_metadata

When you create a transaction through the FedaPay API, it’s often helpful to attach some custom information that comes from your own app or platform. This could be to track the transaction better, connect it to a user account, an order, or a specific business operation. To make this easier, FedaPay offers two key fields you can use: merchant_reference and custom_metadata. Merchant_reference: Your Own Unique ID for Each Transaction The merchant_reference field lets you assign your own identifier to a transaction — for example, an order number, an invoice code, or a session ID from your platform. This reference is stored on FedaPay’s side and can later be used to easily retrieve that transaction. Why Use It?
  • You run an e-commerce site or mobile app and want to match each FedaPay transaction to an internal payment or order.
  • You want to search and filter transactions using your own identifiers, without relying on FedaPay’s generated transaction ID.
  • You need better visibility and tracking of client payments for internal tools or reports.
Example: Creating a Transaction with merchant_reference
Curl
curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions \
-H 'Authorization: Bearer YOUR_SECRET_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "description" : "Transaction for john.doe@example.com",
  "amount" : 2000,
  "currency" : {"iso" : "XOF"},
  "callback_url" : "https://yourapp.com/callback",
  "customer" : {
    "email" : "john.doe@example.com"
  },
  "merchant_reference": "ORD-20250701-001"
}'
Here, ORD-20250701-001 is the merchant’s own code for this specific transaction.
Retrieving a Transaction by Merchant Reference
Curl
curl -X GET \
https://sandbox-api.fedapay.com/v1/transactions/merchant/{reference} \
-H 'Authorization: Bearer YOUR_SECRET_API_KEY' \
-H 'Content-Type: application/json'
custom_metadata: Add Extra Info to a Transaction With the custom_metadata field, you can attach additional data to your transaction. These are key-value pairs that can hold any info useful for your business without impacting how the payment is processed. Use Cases Include:
  • Order ID or user ID
  • Type of service or subscription purchased
  • Sales agent or partner involved
  • Anything else that helps you with automation or reporting
Why Use It?
  • Makes it easier to automate back-office tasks (e.g., reconciliation, reporting, alerts).
  • Avoids having to store sensitive or dynamic data in your own systems.
  • Saves time when reviewing or validating transactions manually.
Example: Creating a Transaction with custom_metadata
Curl
curl -X POST https://sandbox-api.fedapay.com/v1/transactions \
-H 'Authorization: Bearer YOUR_SECRET_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "description": "Premium subscription",
  "amount": 10000,
  "currency": {"iso": "XOF"},
  "callback_url": "https://yourapp.com/callback",
  "customer": {
    "email": "user@yourapp.com"
  },
  "custom_metadata": {
    "client_id": "USER-14567",
    "plan": "premium",
    "language": "fr"
  }
}'
Best Practices :
  • Make sure your merchant_reference is unique for every transaction. If it’s duplicated, the transaction will fail.
  • Only use custom_metadata for non-sensitive data. Don’t store passwords, card numbers, or personal details in this field.
  • Both fields are optional, but they’re powerful tools for improving how your system interacts with FedaPay and how you handle payment workflows internally.