Payouts

Use fee quotes through withdrawal preview to show payout fees and required balance before execution.

Un payout envoie des fonds depuis le solde marchand vers une destination mobile money ou bancaire.

Famille de routes actuellement implémentée : api/v1/payouts

Objet Payout

{
  "id": "po_abc123",
  "object": "payout",
  "amount": 50000,
  "currency": "XOF",
  "status": "in_transit",
  "destination": {
    "type": "mobile_money",
    "country": "SN",
    "operator": "orange_money",
    "msisdn": "+221770000000"
  },
  "arrival_date_estimate": "2026-06-04T12:10:00Z",
  "expected_by": "2026-06-04T12:10:00Z",
  "delay_state": null,
  "delay_reason": null,
  "delayed_at": null,
  "metadata": {
    "batch_id": "batch_123",
    "supplier_id": "sup_456"
  },
  "failure_code": null,
  "failure_message": null
}

Champ	Type	Description
id	string	Identifiant public du payout.
object	string	Toujours payout.
amount	integer:int64	Montant dans la plus petite unité monétaire.
currency	string	Devise du payout.
status	string	Statut courant : pending, in_transit, paid, failed ou canceled.
destination	object	Destination normalisée du payout.
arrival_date_estimate	string:date-time	Estimation héritée d’arrivée.
expected_by	string:date-time	Date estimée de complétion. Pour mobile money, la valeur par défaut est création + 10 minutes.
delay_state	string	delayed lorsque le payout est en retard, sinon null.
delay_reason	string	Raison de retard : operator_pending, operator_timeout, operator_down ou unknown.
delayed_at	string:date-time	Date à laquelle le retard a été détecté.
metadata	object<string,string>	Métadonnées associées au payout.
failure_code	string	Code d’échec lorsque status vaut failed.
failure_message	string	Message d’échec lisible lorsque disponible.

Créer un payout

POST /api/v1/payouts

Authentification :

• ApiKey ou AppToken
• scope payouts.write
• header d’environnement requis
• Idempotency-Key requis en live

Paramètre	Type	Requis	Description
amount	integer:int64	Oui	Montant dans la plus petite unité monétaire. Doit être strictement positif.
currency	string	Oui	Code devise ISO à trois lettres, par exemple XOF.
destination	object	Conditionnel	Destination inline. Requis si payout_method_id n’est pas fourni.
payout_method_id	string:uuid	Conditionnel	Destination de payout enregistrée. Requis si destination n’est pas fourni.
metadata	object<string,string>	Non	Métadonnées métier. Les clés et valeurs doivent être des chaînes.

Vous devez fournir exactement une destination exploitable : soit destination, soit payout_method_id. Si aucune destination n’est fournie, l’API retourne une erreur de destination invalide.

Destination mobile money inline

Paramètre	Type	Requis	Description
destination.type	string	Oui	mobile_money.
destination.currency	string	Non	Devise de la destination. Si absent, currency est utilisé.
destination.country	string	Oui	Code pays ISO 3166-1 alpha-2.
destination.operator	string	Oui	Opérateur mobile money. Le couple country + operator est validé contre le catalogue opérateurs.
destination.msisdn	string	Oui	Numéro mobile money du bénéficiaire au format international.

{
  "amount": 50000,
  "currency": "XOF",
  "destination": {
    "type": "mobile_money",
    "country": "SN",
    "operator": "orange_money",
    "msisdn": "+221770000000"
  },
  "metadata": {
    "batch_id": "batch_123",
    "supplier_id": "sup_456"
  }
}

Destination bancaire inline

Paramètre	Type	Requis	Description
destination.type	string	Oui	bank.
destination.currency	string	Non	Devise de la destination. Si absent, currency est utilisé.
destination.bank_code	string	Oui	Code banque ou routing code.
destination.account_number	string	Oui	Numéro de compte bancaire.
destination.account_name	string	Oui	Nom du titulaire du compte.

{
  "amount": 125000,
  "currency": "XOF",
  "destination": {
    "type": "bank",
    "bank_code": "BANKSNDA",
    "account_number": "SN1234567890",
    "account_name": "Supplier SARL"
  },
  "metadata": {
    "invoice_id": "inv_789"
  }
}

Destination enregistrée

Utilisez payout_method_id lorsqu’une destination a déjà été enregistrée et activée côté marchand.

{
  "amount": 50000,
  "currency": "XOF",
  "payout_method_id": "9b9d7f48-1e63-4f4f-a6dd-9b85f5cc6c8a",
  "metadata": {
    "batch_id": "batch_123"
  }
}

La destination enregistrée doit appartenir au marchand, être active, et ne pas être encore bloquée par un délai de sécurité.

Metadata

metadata est un objet object<string,string> destiné aux références métier comme batch_id, supplier_id, invoice_id, payroll_run_id ou source_system.

Dans les flux exécutés via le payout engine, la plateforme ajoute ou remplace les clés source et environment. Évitez donc d’utiliser ces deux clés pour des valeurs métier que vous devez conserver telles quelles.

Récupérer un payout

GET /api/v1/payouts/{id}

Authentification :

• ApiKey ou AppToken
• scope payouts.read
• header d’environnement requis

Paramètre	Type	Requis	Description
id	string	Oui	Identifiant public du payout.

Règles d’exécution

• Le montant doit être positif.
• La devise est obligatoire.
• En live, Idempotency-Key est obligatoire pour éviter les doubles décaissements.
• Le solde marchand disponible doit couvrir le montant et les frais estimés.
• Les payouts mobile money valident le couple country + operator et l’éligibilité opérateur pour le sens payout.
• Les destinations bancaires inline sont supportées en sandbox via le payout engine et peuvent suivre un chemin legacy selon l’environnement.

Routes marchandes liées

Les routes opérationnelles marchandes sont disponibles sous :

• GET /api/v1/merchant/payouts
• GET /api/v1/merchant/payouts/{id}
• POST /api/v1/merchant/payouts
• GET /api/v1/merchant/settings/payouts
• PATCH /api/v1/merchant/settings/payouts
• POST /api/v1/merchant/settings/payouts/destinations
• DELETE /api/v1/merchant/settings/payouts/destinations/{id}

Des chemins marchands compatibles hérités peuvent aussi être disponibles sous api/merchant/*.

Note d’intégration

La surface publique actuelle expose uniquement la création et la récupération d’un payout. Ne documentez pas l’annulation de payouts ni la liste publique des payouts tant que ces endpoints ne figurent pas dans la référence générée.