Docs
ENFR
Tableau de bord
Produits

Paiements

Envoyez de l’argent vers des portefeuilles mobile money et des comptes bancaires.

Un paiement envoie de l’argent de votre solde vers quelqu’un d’autre : un fournisseur, un salarié, un client. Le mobile money et le virement bancaire utilisent le même point d’accès, dans toutes les devises de Montants et devises, NGN compris.

Mobile money

bash
curl https://api.monerails.com/v1/payouts \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Idempotency-Key: payout-inv-118" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "XAF",
    "recipient": { "type": "mobile_money", "name": "Kossi Mensah", "phone": "237660000001", "operator": "MTN" },
    "client_reference": "inv_118"
  }'

Virement bancaire

En cours d’activation. Les virements bancaires ouvrent avec les marchés en cours d’activation (Ghana, Kenya, Nigéria, Rwanda, Tanzanie et Ouganda). D’ici là, un virement bancaire renvoie 400 bank_transfer_unsupported dans tous les pays, et l’exemple ci-dessous est illustratif.

Trouvez la banque avec Lister les banques et envoyez son code exactement tel que renvoyé. Un nom de banque ou un code qui ne correspond pas exactement échoue avec 400 bank_account_invalid.

JSON
{
  "amount": 5000000,
  "currency": "NGN",
  "recipient": { "type": "bank", "name": "Chidi Okafor", "country": "NG", "bank_code": "044", "account": "0123454821" }
}

Les numéros de compte sont masqués dans toutes les réponses (••••4821).

Argent et statuts

À la création d’un paiement, Monerails réserve amount + fee sur votre solde. S’il ne couvre pas les deux, la requête échoue avec 402 balance_insufficient et rien n’est envoyé.

Statut Sens
pending, processing En route. L’argent est réservé.
succeeded Reçu par le bénéficiaire.
failed Non livré. amount + fee revient sur votre solde, et payout.failed est envoyé.

La réservation apparaît dans les transactions comme un payout au statut pending, puis succeeded, ou failed accompagné d’un payout_reversal qui rend l’argent.

Sécurité

  • Envoyez toujours une Idempotency-Key et un client_reference unique. La clé protège vos nouvelles tentatives pendant 24 heures ; la référence permet de retrouver le paiement ensuite.
  • Les paiements demandent une clé créée par un membre Propriétaire, Finance ou Valideur.
  • Une réponse 202 signifie que le partenaire de paiement n’a pas encore accusé réception. Ne recréez pas le paiement : attendez le webhook, ou consultez-le.