Déboursements

Envoyer des fonds vers un numéro mobile money.

Un seul appel, et l'argent part

Il n'y a pas d'étape d'approbation à déclencher : la création immobilise les fonds et confie l'opération à l'opérateur dans la même requête. Une application qui débourse en continu ne peut pas attendre une validation, et un point d'arrêt que personne ne surveille n'arrête rien.

Ce qui tient lieu de contrôle est automatique : le solde borne le montant, l'adresse d'appel borne l'origine, la cadence borne le rythme, et un versement identique au même bénéficiaire dans la minute est refusé. C'est détaillé plus bas.

POST /api/v1/payouts

curl -X POST https://maticorp.tech/api/v1/payouts \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Idempotency-Key: paie-livreur-nov-12" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiary_name": "Awa Diallo",
    "beneficiary_msisdn": "0190000000",
    "amount": 25000,
    "reason": "Commissions novembre"
  }'

Le solde disponible doit couvrir le montant et les frais. S'il ne suffit pas, la création échoue tout de suite plutôt que de laisser un déboursement impossible en attente.

Si l'opérateur refuse, les fonds immobilisés reviennent au solde disponible — automatiquement, sans action de votre part. Vous le verrez au statut et au webhook, pas en interrogeant un objet resté en attente.

POST /api/v1/payouts/{id}/approve existe encore, mais n'a plus d'usage : un déboursement créé par cet appel est déjà en cours. Il ne sert qu'à débloquer un déboursement resté en attente avant que l'envoi ne devienne direct, et répond approval_rejected sinon.

Autorisation par adresse IP

Un déboursement par API n'est pas approuvé par un humain : il est autorisé par l'adresse d'où part l'appel. Déclarez les adresses de sortie de vos serveurs dans la console, section Développeurs. Tout appel venu d'ailleurs est alors refusé — payout_rejected, le motif étant dans le message.

Tant que vous n'en déclarez aucune, l'appel est accepté de partout — c'est pourquoi il faut le faire avant la mise en production. Une clé API suffirait autrement à vider le solde disponible depuis n'importe où dans le monde.

Cette liste ne se modifie que depuis la console, jamais par l'API : une clé volée ne peut pas s'autoriser une adresse. Deux autres garde-fous s'appliquent en plus — une cadence par minute, réglable par compte, et le refus d'un versement identique au même bénéficiaire dans la minute.

Les statuts

• a_approuver — état de passage, le temps que les fonds soient immobilisés. Vous ne devriez jamais le lire dans une réponse.
• en_cours — fonds immobilisés, opération confiée à l'opérateur.
• execute — le bénéficiaire a été crédité.
• echoue — refusé. Les fonds sont revenus au solde disponible.
• rejete — refusé avant exécution. Ne concerne plus que les déboursements restés en attente avant que l'envoi ne devienne direct.

Un rappel perdu ne bloque rien

Si l'opérateur ne nous rappelle jamais, un sondage périodique relit le statut et dénoue l'opération. Sans lui, des fonds resteraient immobilisés sans fin alors que le bénéficiaire a peut-être déjà été crédité.