Gestion des collectes

L’API de FedaPay permet d’intégrer facilement des solutions de paiement sécurisées dans votre site web ou application. Ce guide vous expliquera en détail comment configurer et gérer la collecte de paiements à l’aide de l’API, de la création initiale à la finalisation du processus, en passant par les fonctionnalités avancées comme les paiements sans redirection. Que vous soyez développeur ou responsable de produits, vous trouverez ici tout le nécessaire pour utiliser FedaPay de manière optimale.

​

Étapes pour Créer et Gérer une Collecte de Paiement

Les étapes de configuration d’une collecte se divisent en plusieurs processus essentiels.

  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'

/*Remplacez YOUR_SECRETE_API_KEY par la clé API secrète de votre compte sandbox ou live. Si vous utilisez votre compte live, vous devez remplacer le lien par 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'

​

Paiements sans Redirection

Pour offrir une expérience fluide sans redirection, vous pouvez intégrer directement le formulaire de paiement dans votre application pour certaines méthodes spécifiques (MTN Bénin, Moov Bénin, Moov Togo, et MTN Côte d’Ivoire). Ce mode de paiement est particulièrement utile pour les sites e-commerce qui souhaitent garder l’utilisateur sur leur plateforme tout au long du processus, sans redirection vers une autre page.

Envoi d’un Paiement Mobile Sans Redirection

Le processus de paiement mobile sans redirection se divise en deux étapes principales dans l’environnement Live ou Sandbox :

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

​

Récupération Automatique du Statut d’une Collecte

Pour vérifier le statut final d’une collecte, surtout lors d’un paiement sans redirection :

• Envoyez une requête pour obtenir les détails de la collecte.

• Implémentez un webhook pour recevoir des notifications automatiques. Consultez la section Webhooks pour plus de détails.

​

Cycle de Vie d’une Collecte : Les Statuts

Chaque collecte passe par différents statuts :

• pending : En attente (statut par défaut à la création)

• approved : Approuvée (paiement réussi)

• declined : Déclinée (interruption volontaire ou accidentelle par le client)

• canceled : Annulée (solde insuffisant ou autre problème de paiement)

• refunded : Remboursée (somme reversée au client)

• transferred : Transférée (montant transféré sur le compte marchand)

​

Ajouter des données personnalisées à vos transactions : merchant_reference et custom_metadata

Lorsque vous créez une transaction via l’API de FedaPay, il est souvent nécessaire d’y associer des informations propres à votre application. Cela vous permet de mieux suivre, analyser ou relier une transaction à un utilisateur ou une commande spécifique sur votre plateforme. FedaPay vous offre deux champs très utiles pour cela : merchant_reference et custom_metadata.

merchant_reference : Votre identifiant unique pour chaque transaction

Le champ merchant_reference vous permet d’attribuer à chaque transaction un identifiant unique défini par vous-même (par exemple : un ID de commande, un numéro de facture ou le code d’une session d’achat). Cet identifiant est stocké par FedaPay et peut ensuite être utilisé pour retrouver facilement la transaction via une API dédiée.

Pourquoi l’utiliser ?

• Vous avez une plateforme e-commerce ou une application mobile et souhaitez lier une transaction FedaPay à un paiement interne.

• Vous souhaitez retrouver rapidement une transaction en utilisant vos propres références, sans avoir à stocker l’ID généré par FedaPay.

• Vous voulez tracer plus facilement les paiements effectués par vos clients.

Exemple : Créer une transaction avec merchant_reference

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" : {
        "email" : "john.doe@example.com",
      },
      "merchant_reference": "CMD-20250701-001" 
    }'

Récupérer une transaction avec la référence marchand

curl -X GET \
https://sandbox-api.fedapay.com/v1/transactions/merchant/{reference}
 \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json'

custom_metadata : Ajouter des données personnalisées à vos transactions

Avec le champ custom_metadata, vous pouvez enregistrer des informations supplémentaires directement dans la transaction. Il peut s’agir, par exemple :

• Le numéro de la commande

• Du type de service acheté

• De l’identifiant de l’agent vendeur

• Ou toute autre donnée utile pour vous.

Ces données sont stockées sous forme de paires clé-valeur et restent attachées à la transaction, sans affecter son traitement.

Pourquoi l’utiliser ?

• Pour enrichir vos rapports internes ou automatiser certains traitements en récupérant vos propres données.

• Pour éviter de stocker des informations sensibles côté client.

• Pour gagner du temps lors du rapprochement comptable ou des vérifications manuelles.

Exemple : Créer une transaction avec custom_metadata

curl -X POST https://sandbox-api.fedapay.com/v1/transactions \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json' \
-d '{
  "description": "Abonnement premium",
  "amount": 10000,
  "currency": {"iso": "XOF"},
  "callback_url": "https://votreapp.com/callback",
  "customer": {
    "email": "utilisateur@votreapp.com"
  },
  "custom_metadata": {
    "client_id": "USER-14567",
    "forfait": "premium",
    "langue": "fr"
  }
}'