Envoyez de l’argent à des bénéficiaires via une méthode enregistrée ou des détails fournis à la volée.

API Payouts

Les payouts servent à décaisser vers des utilisateurs, partenaires ou commerçants.

Headers requis

X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

Endpoints

GET /api/v1/payouts

POST /api/v1/payouts

GET /api/v1/payouts/balance

GET /api/v1/payouts/{id}

POST /api/v1/payouts/{id}/cancel

POST /api/v1/payouts/{id}/retry

Initier un payout

POST /api/v1/payouts

Champs de requête

Paramètre	Type	Requis	Description
amount	number	Oui	Montant
currency	string	Oui	Code ISO
country	string	Non	Pays du bénéficiaire
payment_method_id	string	Conditionnel	Méthode enregistrée
recipient_phone	string	Conditionnel	Téléphone au format E.164 si aucune méthode enregistrée, ex. `+237677001122`
operator_code	string	Conditionnel	Opérateur si aucune méthode enregistrée
recipient_first_name	string	Non	Prénom
recipient_last_name	string	Non	Nom
external_id	string	Non	Référence interne
description	string	Non	Description métier
metadata	object	Non	Métadonnées

Vous devez fournir soit :

payment_method_id

soit recipient_phone et operator_code

Exemple

curl -X POST "{{BASE_URL}}/api/v1/payouts" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "XAF",
    "recipient_phone": "+237677001122",
    "operator_code": "MTN_MOMO",
    "recipient_first_name": "Jean",
    "recipient_last_name": "Mballa",
    "external_id": "payout_9001",
    "description": "Vendor settlement"
  }'

Les codes opérateur valides sont listés dans Pays et opérateurs. Un operator_code inconnu ou inactif est rejeté en 422.

Consulter un payout

GET /api/v1/payouts/{id}

Annuler un payout

POST /api/v1/payouts/{id}/cancel

L’annulation dépend du statut courant et de l’avancement chez l’opérateur.

Relancer un payout

POST /api/v1/payouts/{id}/retry

Relance un décaissement en échec, sans recréer de transaction.

Consulter le solde disponible

GET /api/v1/payouts/balance

Le solde décaissable de votre compte de règlement, dans la devise du corridor.

Statuts

Statut	Description
`AWAITING_APPROVAL`	En attente de validation avant exécution
`INITIATED`	Validé, pas encore transmis à l’opérateur
`PROCESSING`	Transmis, en cours de traitement
`SUCCESS`	Fonds remis au bénéficiaire
`FAILED`	Échec. Peut être relancé.
`EXPIRED`	Sans réponse de l’opérateur dans le délai imparti
`CANCELLED`	Annulé avant exécution

Les minimums de décaissement varient par opérateur — lisez min_payout_amount sur l’endpoint de couverture plutôt que de les coder en dur.

API Payouts

On this page