Passer au contenu principal
Utilisez les décaissements Payfonte pour envoyer des fonds à des bénéficiaires validés via les providers et marchés pris en charge.

​
Résumé du flux

1. Valider le bénéficiaire

Confirmez les informations du compte bénéficiaire avant le décaissement.

2. Demander le décaissement

Initiez le décaissement avec le montant, l’identifiant du bénéficiaire et le mode d’autorisation.

3. Vérifier le statut final

Confirmez le résultat via l’endpoint de vérification et/ou le webhook.

​
Vue d’ensemble du flux de décaissement

​
Endpoints

MéthodeEndpointObjet
GET/billing/v1/transfer-recipients/{provider}/propertiesRécupérer les propriétés spécifiques au provider, optionnel
POST/billing/v1/transfer-recipients/validateValider les informations du bénéficiaire
POST/billing/v1/disbursementsDemander un décaissement
GET/billing/v1/disbursements/verify/{reference}Vérifier le statut du décaissement

​
Prérequis

  • Un client-id et un client-secret valides
  • Un solde suffisant dans le portefeuille de décaissement
  • Une configuration d’autorisation du décaissement, pin ou URL d’autorisation
  • Un slug provider valide depuis Providers pris en charge

​
Étape 1 : valider le bénéficiaire

​
1.1 Récupérer les propriétés du provider, optionnel

Certains providers requièrent des détails supplémentaires, par exemple une liste de banques ou des options de réseau, avant la validation. 
curl --location 'https://sandbox-api.payfonte.com/billing/v1/transfer-recipients/{provider}/properties' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>'

​
1.2 Valider le bénéficiaire

Exemple pour un virement bancaire : 
{
  "currency": "NGN",
  "country": "NG",
  "provider": "bank-transfer-nigeria",
  "account": {
    "accountNumber": "0123456789",
    "bankCode": "044"
  }
}
Exemple pour le mobile money : 
{
  "currency": "XOF",
  "country": "CI",
  "provider": "wave-ivory-coast",
  "account": {
    "phoneNumber": "2250538102474"
  }
}
Exemple de réponse : 
{
  "data": {
    "id": "recipient-id",
    "currency": "NGN",
    "country": "NG",
    "provider": "bank-transfer-nigeria",
    "accountLabel": "Bank Transfer | Zenith Bank | Dummy User | 0123456789",
    "account": {
      "accountNumber": "0123456789",
      "bankCode": "044"
    }
  }
}
Enregistrez data.id comme transferRecipientId.

​
Étape 2 : demander le décaissement

curl --location 'https://sandbox-api.payfonte.com/billing/v1/disbursements' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "transferRecipientId": "6659692f019f6a143f7f90db",
    "amount": 100000,
    "reference": "Disbursement-1001",
    "narration": "Vendor settlement",
    "pin": "1234",
    "webhookURL": "https://yourapp.com/webhooks/payfonte"
  }'
Exemple de réponse : 
{
  "data": {
    "reference": "Disbursement-1001",
    "amount": 100000,
    "amountPayable": 100000,
    "provider": "bank-transfer-nigeria",
    "currency": "NGN",
    "country": "NG",
    "status": "processing"
  }
}

​
Champs de requête

ChampTypeRequisDescription
transferRecipientIdstringOuiID issu de l’étape de validation du bénéficiaire
amountintegerOuiMontant en sous-unités, sans décimales
referencestringRecommandéRéférence de décaissement unique
narrationstringNonDescription du décaissement
pinstringConditionnelRequis lorsque le mode PIN est activé
webhookURLstringNonURL webhook spécifique à ce décaissement

​
Valeurs de statut

Les statuts de décaissement renvoyés par l’API sont :
  • processing
  • success
  • failed

​
Étape 3 : vérifier le décaissement

curl --location 'https://sandbox-api.payfonte.com/billing/v1/disbursements/verify/Disbursement-1001' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>'
Exemple de réponse : 
{
  "data": {
    "status": "success",
    "reference": "Disbursement-1001",
    "externalReference": "Disbursement-1001",
    "amount": 100000,
    "currency": "NGN"
  }
}

​
Règle de montant importante

Payfonte ne prend pas en charge les montants API décimaux. Envoyez uniquement des valeurs entières en sous-unités.
  • 1000.00 NGN -> 100000
  • 250.75 NGN -> 25075
Voir Spécification des montants.

​
Bonnes pratiques

Toujours valider le bénéficiaire d'abord

La validation réduit les échecs de décaissement dus à des coordonnées invalides.
Réutilisez les bénéficiaires déjà validés afin d’éviter des validations répétées.
Des références uniques évitent les doublons et simplifient le rapprochement.
Traitez les événements webhook et vérifiez le statut final pour les actions métier critiques.
Gardez le PIN de décaissement et les URL d’autorisation strictement côté serveur.

​
Documentation associée

Mode d'autorisation

Configurez le mode PIN ou URL d’autorisation.

Exemples de décaissement

Exemples de requêtes et réponses.

Webhooks de décaissement

Traitez les mises à jour de statut de manière asynchrone.