Transfert (Payout)

Élément	Description
Méthode	`POST`
Endpoint	`/v1/payout`
Auth	✅ `Authorization: Basic base64(api_key:api_client)`
Idempotence	✅ `X-Idempotency-Key` obligatoire pour éviter les doublons
Payload Type	`application/json`
Timeout recommandé	30 secondes maximum

Headers

Key	Description	Obligatoire
`Authorization`	Basic base64(api_key:api_client)	✅
`X-Idempotency-Key`	UUID garantissant l’unicité de la requête	✅

Request Body

{
  "reference": "55a4e677-5700-4ed0-9a2a-9300db894ddb",
  "accountId": "merchant_qdadaklwldakld",
  "amount": 300,
  "msisdn": "+2250749929598",
  "country": "CI",
  "customerName": "Habib"
}

Description des paramètres

Champ	Type	Description	Obligatoire
`reference`	`string`	Identifiant unique du transfert (UUID côté marchand).	✅
`accountId`	`string`	Compte ou sous-compte marchand à débiter.	✅
`amount`	`number`	Montant à transférer.	✅
`msisdn`	`string`	Numéro de téléphone du bénéficiaire (format E.164).	✅
`country`	`string`	Code ISO du pays (`CI`, `SN`, `TG`, etc.).	✅
`customerName`	`string`	Nom du bénéficiaire.	✅

Exemple de Réponse

{
  "type": "payout",
  "fee": 6,
  "reference": "mtr_fhscgaywizujwjyymlge1hncaq",
  "phoneNumber": "+2250749929598",
  "customerName": "Habib",
  "amount": 300,
  "chargedAmount": 306,
  "status": "processed",
  "currency": "XOF",
  "customerReference": "55a4e677-5700-4ed0-9a2a-9300db894ddb",
  "confirmationRequired": false,
  "confirmationStatus": "none",
  "transaction": {
    "reference": "TFHL2A4D3QQC11NW9",
    "status": "completed",
    "processedAt": "2025-08-29T13:39:35.138Z",
    "phoneNumber": "+2250749929598",
    "amount": "300.00",
    "fees": "6.00",
    "chargedAmount": "306.00",
    "currency": "XOF"
  },
  "createdAt": "2025-08-22T02:00:16.026Z"
}

Interprétation de la Réponse

Champ	Description
type	Type de transaction — ici `payout` (transfert sortant).
fee	Montant des frais de service appliqués.
reference	Référence système du transfert côté API.
phoneNumber	Numéro du bénéficiaire du transfert.
customerName	Nom du bénéficiaire.
amount	Montant à transférer (hors frais).
chargedAmount	Montant total débité du compte marchand (montant + frais).
status	Statut global du transfert (`processing`, `processed`, `expired`, etc.).
currency	Devise utilisée (`XOF`, `USD`, `EUR`, etc.).
customerReference	Référence d’origine fournie par le marchand pour corrélation.
confirmationRequired	Indique si le bénéficiaire doit confirmer avant réception. (Souvent `false` pour les transferts marchands classiques.)
confirmationStatus	Statut de confirmation (utile si une validation bénéficiaire est exigée).
transaction	Détails finaux du transfert exécuté dans le Core System.
createdAt	Horodatage de création du transfert.

Clé `transaction`

Ce champ contient les informations de la transaction finale une fois que le transfert est traité par le processeur Mobile Money ou le Core interne.

Champ	Description
transaction.reference	Référence technique générée par le système de traitement.
transaction.status	Statut final (`completed`, `failed`, `pending`).
transaction.processedAt	Timestamp de finalisation du transfert.
transaction.phoneNumber	Numéro du compte crédité.
transaction.amount	Montant exact crédité.
transaction.fees	Frais appliqués au niveau du processeur.
transaction.chargedAmount	Montant total débité du compte marchand.
transaction.currency	Devise utilisée.

💡 Le champ transaction devient disponible une fois le transfert traité avec succès.

S’il est vide ({}), cela signifie que le transfert est encore en cours (status = processing).

Statut d’un Transfert

GET /v1/payout/{reference}

Élément	Description
Méthode	`GET`
Endpoint	`/v1/payout/{reference}`
Auth	✅ `Authorization` requise
Payload	Aucun
Description	Retourne le statut complet du transfert correspondant à la `reference` fournie.

Exemple de Réponse

{
  "type": "payout",
  "fee": 6,
  "reference": "mtr_fhscgaywizujwjyymlge1hncaq",
  "phoneNumber": "+2250749929598",
  "customerName": "Habib",
  "amount": 300,
  "chargedAmount": 306,
  "status": "processed",
  "currency": "XOF",
  "customerReference": "55a4e677-5700-4ed0-9a2a-9300db894ddb",
  "confirmationRequired": false,
  "confirmationStatus": "none",
  "createdAt": "2025-08-22T02:00:16.026Z",
  "transaction": {},
  "failure": null
}

Interprétation de la Réponse

Champ	Description
status	Statut global du transfert.
transaction	Objet contenant les informations finales (vide si non encore traité).
failure	Détails d’erreur en cas d’échec (`null` si succès).

Statuts Possibles

Statut	Description
pending	Requête reçue, en attente de traitement.
processing	Transfert en cours d’exécution (contact opérateur Mobile Money).
processed	Transfert traité côté API, résultat en attente du processeur.
completed	Transfert confirmé et crédité sur le compte bénéficiaire.
failed	Erreur de traitement (numéro invalide, solde insuffisant, etc.).
reversed	Fonds reversés au marchand suite à un échec ou une annulation.
expired	Délai de traitement dépassé sans réponse.

Cycle de Vie d’un Transfert (Payout)

Bonnes Pratiques

Utiliser X-Idempotency-Key pour éviter les transferts en double.
Vérifier le status ou s’abonner au webhook payout.completed pour recevoir la confirmation finale.
En cas de failure, consulter le champ failure pour le détail de l’erreur (code, message, opérateur).
Ne pas tenter de relancer manuellement un transfert sans vérifier le statut failed ou expired.
Pour un suivi temps réel, utiliser le WebSocket ou les Webhooks (payout.updated, payout.completed).

Paiement (Payin)Consultation du Solde

Transfert (Payout)

Headers

Request Body

Description des paramètres

Exemple de Réponse

Interprétation de la Réponse

Clé transaction

Statut d’un Transfert

Exemple de Réponse

Interprétation de la Réponse

Statuts Possibles

Cycle de Vie d’un Transfert (Payout)

Bonnes Pratiques

Clé `transaction`