Vue d'ensemble

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éthode	Endpoint	Objet
`GET`	`/billing/v1/transfer-recipients/{provider}/properties`	Récupérer les propriétés spécifiques au provider, optionnel
`POST`	`/billing/v1/transfer-recipients/validate`	Valider les informations du bénéficiaire
`POST`	`/billing/v1/disbursements`	Demander 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

Champ	Type	Requis	Description
`transferRecipientId`	string	Oui	ID issu de l’étape de validation du bénéficiaire
`amount`	integer	Oui	Montant en sous-unités, sans décimales
`reference`	string	Recommandé	Référence de décaissement unique
`narration`	string	Non	Description du décaissement
`pin`	string	Conditionnel	Requis lorsque le mode PIN est activé
`webhookURL`	string	Non	URL 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.

Conserver les identifiants de bénéficiaire

Réutilisez les bénéficiaires déjà validés afin d’éviter des validations répétées.

Utiliser des références uniques

Des références uniques évitent les doublons et simplifient le rapprochement.

Combiner webhook et vérification

Traitez les événements webhook et vérifiez le statut final pour les actions métier critiques.

Protéger les contrôles d'autorisation

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.

Premiers pas

Concepts clés

Prestataires et couverture

Développement

Encaisser des paiements

Décaissements

Résumé du flux

1. Valider le bénéficiaire

2. Demander le décaissement

3. Vérifier le statut final

Vue d’ensemble du flux de décaissement

Endpoints

Prérequis

Étape 1 : valider le bénéficiaire

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

1.2 Valider le bénéficiaire

Étape 2 : demander le décaissement

Champs de requête

Valeurs de statut

Étape 3 : vérifier le décaissement

Règle de montant importante

Bonnes pratiques

Documentation associée

Mode d'autorisation

Exemples de décaissement

Webhooks de décaissement

​Résumé du flux

1. Valider le bénéficiaire

2. Demander le décaissement

3. Vérifier le statut final

​Vue d’ensemble du flux de décaissement

​Endpoints

​Prérequis

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

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

​1.2 Valider le bénéficiaire

​Étape 2 : demander le décaissement

​Champs de requête

​Valeurs de statut

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

​Règle de montant importante

​Bonnes pratiques

​Documentation associée

Mode d'autorisation

Exemples de décaissement

Webhooks de décaissement

Résumé du flux

Vue d’ensemble du flux de décaissement

Endpoints

Prérequis

Étape 1 : valider le bénéficiaire

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

1.2 Valider le bénéficiaire

Étape 2 : demander le décaissement

Champs de requête

Valeurs de statut

Étape 3 : vérifier le décaissement

Règle de montant importante

Bonnes pratiques

Documentation associée