Docs
ENFR
Tableau de bord
Référence de l’API

Paiements

Un paiement envoie de l’argent de votre solde vers un portefeuille mobile money ou un compte bancaire. Le montant et les frais sont réservés à la création, et rendus si le paiement échoue.

L’objet paiement

Attributs
idstring

Identifiant unique (UUID).

livemodeboolean

true en production, false en mode test.

objectstring

Toujours payout.

statusstring

succeeded et failed sont définitifs. En cas d’échec, le montant et les frais reviennent sur votre solde.

pendingprocessingsucceededfailed
amountinteger

Montant reçu par le bénéficiaire, en unités mineures.

currencystring

Code devise ISO 4217.

feeinteger

Frais Monerail, débités de votre solde en plus de amount.

recipientobject

Le bénéficiaire. Les numéros de compte bancaire sont masqués.

Voir les attributs
typestring
mobile_moneybank
namestring

Nom du bénéficiaire.

operatorstring

Mobile money seulement : code opérateur.

phonestring

Mobile money seulement : numéro, format international.

bank_codestring

Banque seulement : code issu de Lister les banques.

accountstring

Banque seulement : numéro de compte masqué.

countrystring

Code pays.

descriptionstring | null

Votre description.

client_referencestring | null

Votre propre référence, telle qu’envoyée à la création.

metadataobject

Paires clé-valeur jointes à la création.

failure_codestring | null

Raison de l’échec, si status vaut failed ou expired.

failure_messagestring | null

Détail transmis par le partenaire de paiement, s’il existe.

created_atstring

Date de création, ISO 8601 (UTC).

updated_atstring

Dernière modification, ISO 8601 (UTC).

L’objet paiement
{
  "id": "7b05e2b6-6638-4088-a984-7155dfd6a036",
  "object": "payout",
  "livemode": false,
  "status": "pending",
  "amount": 150000,
  "currency": "XAF",
  "fee": 2250,
  "recipient": {
    "type": "mobile_money",
    "name": "Kossi Mensah",
    "operator": "MTN",
    "phone": "237670000777",
    "country": "CM"
  },
  "description": "Invoice 2026-118",
  "client_reference": "inv_118",
  "metadata": {},
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Créer un paiement

POST/v1/payouts

Réserve amount + fee sur votre solde et envoie le paiement. Échoue avec 402 balance_insufficient si votre solde ne couvre pas les deux. Renvoie 201, ou 202 avec status: "processing" si le partenaire de paiement n’a pas encore accusé réception : ne recréez pas le paiement, son résultat arrive par webhook.

Rôles de la clé : Propriétaire, Finance ou Valideur

Corps
amountintegerRequis

Montant en unités mineures de currency (francs entiers pour XAF, XOF et GNF ; centimes pour CDF, par multiples de 100). Entier seulement.

currencystringRequis

Code ISO 4217.

XAFXOFGNFCDFNGNKESGHSUGXTZSRWF
recipientobjectRequis

Le bénéficiaire.

Voir les attributs
typestringRequis
mobile_moneybank
namestringRequis

Nom du bénéficiaire, 2 à 80 caractères.

phonestringFacultatif

Mobile money : numéro du bénéficiaire.

operatorstringFacultatif

Mobile money : code opérateur.

bank_codestringFacultatif

Banque : un code issu de Lister les banques, exactement tel que renvoyé. Les noms et codes partiels sont refusés avec 400 bank_account_invalid.

accountstringFacultatif

Banque : numéro de compte.

countrystringFacultatif

ISO 3166-1 alpha-2. Par défaut, le pays principal de la devise (CM pour XAF, SN pour XOF, GN pour GNF, CD pour CDF). Les virements bancaires sont disponibles dans les pays indiqués avec virement dans Couverture.

descriptionstringFacultatif

500 caractères au plus.

client_referencestringFacultatif

Votre propre référence, 64 caractères au plus : lettres, chiffres et _ . : / -.

metadataobjectFacultatif

Jusqu’à 20 paires clé-valeur. Clés de 40 caractères au plus (A-Z a-z 0-9 _ . -), valeurs enregistrées en texte, 500 caractères au plus.

Retour

Renvoie le nouvel objet paiement avec 201, ou 202 quand le résultat n’est pas encore définitif.

Erreurs à prévoir
HTTPCodeDescription
402balance_insufficientVotre solde (ou solde cartes) ne couvre pas le montant et les frais.
400bank_account_invalidbank_code ne correspond pas exactement à un code de Lister les banques, ou le numéro de compte est trop court.
400bank_transfer_unsupportedLes virements bancaires ne sont pas disponibles dans ce pays : payez vers un portefeuille mobile money.
400country_unsupportedCe pays n’est pas ouvert pour cette devise. Voir Couverture.
400test_phone_requiredMode test : utilisez un des numéros de test de ce pays. Voir Tests.
402recipient_invalidLe partenaire de paiement a refusé le bénéficiaire.
403permission_deniedLe créateur de la clé n’a pas le rôle requis pour cette opération.
429rate_limitedUne limite de débit est atteinte. Attendez Retry-After secondes. Voir Limites de débit.
503provider_insufficient_fundsLe partenaire de paiement ne peut pas traiter ce paiement pour l’instant. Réessayez plus tard.
curl https://api.monerail.com/v1/payouts \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1f3c9e2-5b7d-4c21-9f80-3e6b2d1c7a45" \
  -d '{
    "amount": 150000,
    "currency": "XAF",
    "recipient": {
      "type": "mobile_money",
      "name": "Kossi Mensah",
      "phone": "237670000777",
      "operator": "MTN"
    },
    "description": "Invoice 2026-118",
    "client_reference": "inv_118"
  }'
Réponse201
{
  "id": "7b05e2b6-6638-4088-a984-7155dfd6a036",
  "object": "payout",
  "livemode": false,
  "status": "pending",
  "amount": 150000,
  "currency": "XAF",
  "fee": 2250,
  "recipient": {
    "type": "mobile_money",
    "name": "Kossi Mensah",
    "operator": "MTN",
    "phone": "237670000777",
    "country": "CM"
  },
  "description": "Invoice 2026-118",
  "client_reference": "inv_118",
  "metadata": {},
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:06.394Z"
}

Consulter un paiement

GET/v1/payouts/{id}

Si le paiement est encore en route, Monerail interroge d’abord le partenaire de paiement.

Rôles de la clé : Tous les rôles

Paramètres de chemin
idstringRequis

Identifiant du paiement.

Retour

Renvoie l’objet paiement.

curl https://api.monerail.com/v1/payouts/7b05e2b6-6638-4088-a984-7155dfd6a036 \
  -H "Authorization: Bearer $MONERAIL_KEY"
Réponse200
{
  "id": "7b05e2b6-6638-4088-a984-7155dfd6a036",
  "object": "payout",
  "livemode": false,
  "status": "succeeded",
  "amount": 150000,
  "currency": "XAF",
  "fee": 2250,
  "recipient": {
    "type": "mobile_money",
    "name": "Kossi Mensah",
    "operator": "MTN",
    "phone": "237670000777",
    "country": "CM"
  },
  "description": "Invoice 2026-118",
  "client_reference": "inv_118",
  "metadata": {},
  "failure_code": null,
  "failure_message": null,
  "created_at": "2026-10-30T13:47:06.394Z",
  "updated_at": "2026-10-30T13:47:09.807Z"
}

Lister les paiements

GET/v1/payouts

Du plus récent au plus ancien.

Rôles de la clé : Tous les rôles

Paramètres de requête
limitintegerFacultatifPar défaut 20

Nombre d’objets à renvoyer, de 1 à 100.

starting_afterstringFacultatif

Curseur : l’identifiant du dernier objet de la page précédente.

Retour

Renvoie un objet liste : data contient jusqu’à limit objets payout, et has_more indique s’il en reste.

curl "https://api.monerail.com/v1/payouts?limit=10" \
  -H "Authorization: Bearer $MONERAIL_KEY"
Réponse200
{
  "object": "list",
  "url": "/v1/payouts",
  "data": [
    {
      "id": "7b05e2b6-6638-4088-a984-7155dfd6a036",
      "object": "payout",
      "livemode": false,
      "status": "pending",
      "amount": 150000,
      "currency": "XAF",
      "fee": 2250,
      "recipient": {
        "type": "bank",
        "name": "Kossi Mensah",
        "bank_code": "10005",
        "account": "••••4821",
        "country": "CM"
      },
      "description": "Invoice 2026-118",
      "client_reference": "inv_118",
      "metadata": {},
      "failure_code": null,
      "failure_message": null,
      "created_at": "2026-10-30T13:47:06.394Z",
      "updated_at": "2026-10-30T13:47:06.394Z"
    }
  ],
  "has_more": false
}