API Payouts
Demandez un décaissement vers une méthode enregistrée ou un numéro fourni à la volée, puis suivez sa validation.
Les payouts servent à décaisser depuis votre solde vers des utilisateurs, partenaires ou fournisseurs.
Chaque payout est validé à la main
Un payout créé par API ou depuis le dashboard part en AWAITING_APPROVAL. L'équipe Genuka Pay le valide, exécute le transfert, puis le marque comme réussi. Votre solde n'est débité qu'à ce moment-là. Comptez donc un délai entre la demande et la réception des fonds, et ne présentez pas un payout comme « envoyé » à sa création.
Headers requis
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE
Idempotency-Key: VOTRE_CLE_UNIQUE # optionnel, POST /payouts uniquementEndpoints
GET /api/v1/payoutsPOST /api/v1/payoutsGET /api/v1/payouts/balanceGET /api/v1/payouts/{id}POST /api/v1/payouts/{id}/cancelPOST /api/v1/payouts/{id}/retry
Initier un payout
POST /api/v1/payoutsChamps de requête
| Paramètre | Type | Requis | Description |
|---|---|---|---|
amount | number | Oui | Montant, minimum 1 |
currency | string | Oui | XAF ou XOF |
country | string | Non | Pays du bénéficiaire (code ISO 2 lettres) |
payment_method_id | string | Conditionnel | Une méthode de paiement de votre entreprise |
recipient_phone | string | Conditionnel | Téléphone au format E.164, ex. +237677001122. Requis sans payment_method_id. |
operator_code | string | Conditionnel | Opérateur actif du bénéficiaire. Requis sans payment_method_id. |
recipient_first_name | string | Non | Prénom (100 caractères max) |
recipient_last_name | string | Non | Nom (100 caractères max) |
external_id | string | Non | Référence interne. Sert de clé d'idempotence sans Idempotency-Key. |
description | string | Non | Description métier (255 caractères max) |
metadata | object | Non | Métadonnées |
Vous devez fournir soit :
payment_method_id- soit
recipient_phoneetoperator_code
Il n'y a pas de méthode « par défaut » : sans payment_method_id, le bénéficiaire doit être décrit dans la requête.
Exemple
curl -X POST "https://api-pay.genuka.com/api/v1/payouts" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Idempotency-Key: payout_9001" \
-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. Un montant supérieur à votre solde disponible (solde moins les payouts déjà en attente) est refusé.
Réponse
Code HTTP 202 :
{
"data": {
"id": "01k7c4t9m2y8x5b3n6q0r1s2t3",
"reference": "01k7c4t9m3...",
"track_id": "PX-01k7c4t9m2y8x5b3n6q0r1s2t4",
"idempotency_key": "payout_9001",
"amount": 25000,
"currency": "XAF",
"provider_fee_amount": null,
"genuka_fee_amount": null,
"total_fee_amount": null,
"net_amount": null,
"status": "AWAITING_APPROVAL",
"type": "PAYOUT",
"recipient_phone": "+237677001122",
"recipient_name": "Jean Mballa",
"operator_code": "MTN_MOMO",
"failure": null,
"rejection_reason": null,
"created_at": "2026-09-19T10:00:00.000000Z",
"completed_at": null,
"fee_breakdown": { "...": "..." }
}
}Une requête rejouée avec la même clé d'idempotence renvoie le payout existant au lieu d'en créer un second.
Lister les payouts
GET /api/v1/payoutsParamètres : per_page, filter[status], filter[from] et filter[to] (dates), filter[phone] (numéro du bénéficiaire, recherche partielle), sort (created_at, amount, status, reference, préfixe - pour décroissant ; -created_at par défaut).
Consulter un payout
GET /api/v1/payouts/{id}{id} est l'id du payout (pas son track_id). Ajoutez ?sync=1 pour demander une resynchronisation du statut avant la réponse.
Annuler un payout
POST /api/v1/payouts/{id}/cancelSeul un payout encore en attente d’approbation (AWAITING_APPROVAL) peut être annulé. Une fois approuvé, le décaissement est peut-être déjà en cours : l’annulation est refusée avec une erreur 400. Annuler un payout déjà annulé ou en échec ne change rien.
Relancer un payout
POST /api/v1/payouts/{id}/retryRemet un payout en échec (FAILED) en attente d’approbation (AWAITING_APPROVAL), sans recréer de transaction. Il est de nouveau soumis à validation, et votre solde disponible est revérifié : la relance est refusée s’il ne couvre plus le montant.
Consulter le solde disponible
GET /api/v1/payouts/balance{
"data": {
"current_balance": 150000,
"pending_payouts_amount": 25000,
"available_balance": 125000,
"currency": "XAF",
"environment": "LIVE",
"settlement_account_id": "01k5...",
"can_payout": true
}
}available_balance est ce que vous pouvez encore demander : le solde moins les payouts en attente, qui ne sont débités qu’à leur exécution. can_payout vaut false tant qu’aucun compte de règlement n’existe pour cet environnement. La réponse contient aussi country, le pays de votre entreprise.
Statuts
| Statut | Description |
|---|---|
AWAITING_APPROVAL | Demande reçue, en attente de validation par Genuka Pay |
PROCESSING | Validé, transfert en cours |
SUCCESS | Fonds remis au bénéficiaire, solde débité |
FAILED | Échec. Peut être relancé (retour en attente d’approbation). |
CANCELLED | Annulé par vous, ou refusé lors de la validation — rejection_reason en donne alors la raison |
Suivre un payout
Les changements de statut d’un payout ne déclenchent aujourd’hui aucun webhook : les événements payout.* peuvent être cochés sur un endpoint mais ne sont pas encore émis. Relisez le payout avec GET /api/v1/payouts/{id} pour suivre sa progression.
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.
How is this guide?
Last updated on