Logo GenukaGenuka Pay
Référence API

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 uniquement

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ètreTypeRequisDescription
amountnumberOuiMontant, minimum 1
currencystringOuiXAF ou XOF
countrystringNonPays du bénéficiaire (code ISO 2 lettres)
payment_method_idstringConditionnelUne méthode de paiement de votre entreprise
recipient_phonestringConditionnelTéléphone au format E.164, ex. +237677001122. Requis sans payment_method_id.
operator_codestringConditionnelOpérateur actif du bénéficiaire. Requis sans payment_method_id.
recipient_first_namestringNonPrénom (100 caractères max)
recipient_last_namestringNonNom (100 caractères max)
external_idstringNonRéférence interne. Sert de clé d'idempotence sans Idempotency-Key.
descriptionstringNonDescription métier (255 caractères max)
metadataobjectNonMétadonnées

Vous devez fournir soit :

  • payment_method_id
  • soit recipient_phone et operator_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/payouts

Paramè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}/cancel

Seul 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}/retry

Remet 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

StatutDescription
AWAITING_APPROVALDemande reçue, en attente de validation par Genuka Pay
PROCESSINGValidé, transfert en cours
SUCCESSFonds remis au bénéficiaire, solde débité
FAILEDÉchec. Peut être relancé (retour en attente d’approbation).
CANCELLEDAnnulé 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