Collects management

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.

  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"
            }
          }
      }'

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

/*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'

​

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:

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"
  }
}'

​

Automatic Retrieval of Collect Status

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

• Send a request to retrieve the collection’s details.

• Implement a webhook to receive automatic notifications. See the Webhooks section for more details..

​

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)

​

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 -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"
}'

Retrieving a Transaction by Merchant Reference

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 -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"
  }
}'