Skip to main content
POST
Initier un payout
Whitelist IP obligatoire pour une clé API. Si aucune IP n’est whitelistée pour votre marchand, cet appel échoue avec 403 ip_not_whitelisted, quelle que soit la validité de votre clé. Ajoutez l’IP de votre serveur depuis votre tableau de bord (ou via POST /merchant-ip-whitelist-entries/, accessible par clé API) avant votre premier appel. Ce prérequis ne s’applique pas à un appel authentifié via le dashboard (JWT).
Contrairement à l’encaissement, le mismatch entre currency et country est ici rejeté (422 currency_country_mismatch), sans conversion automatique.
Voir Pays, réseaux et format du téléphone pour la liste des codes method valides par pays et le format attendu de recipient.msisdn.

Éviter un doublon en cas de coupure réseau

Le header Idempotency-Key est optionnel : sans lui, chaque appel crée un décaissement — un simple retry réseau en envoie donc un second au bénéficiaire. Avec lui, renvoyer la même clé après un timeout vous renvoie la réponse d’origine au lieu de rejouer l’opération. Un timeout n’est jamais la preuve qu’une requête a échoué : elle a pu aboutir côté serveur. C’est précisément ce cas que la clé couvre.
Générez une clé par intention (un UUID convient), et réutilisez-la pour chaque retry de cette même tentative. Réutiliser une clé avec un corps différent renvoie 409. Détails : Idempotence.

Authorizations

Authorization
string
header
required

Clé API secrète du marchand — header Authorization: Bearer sk_live_xxx (ou sk_test_xxx en environnement de test).

Headers

Idempotency-Key
string

Identifiant unique que vous générez pour cette tentative (un UUID par exemple). Optionnel : sans lui, chaque appel est traité comme une nouvelle demande. Avec lui, si vous renvoyez la même clé — après un timeout ou une coupure réseau — AlphaPay renvoie la réponse d'origine au lieu de créer un second paiement. Réutilisez la même clé pour les retrys d'une même tentative, changez-en pour toute nouvelle intention. La même clé avec un corps de requête différent renvoie une erreur 409. Voir Idempotence.

Maximum string length: 255

Body

application/json
amount
string<decimal>
required
Example:

"10000.00"

currency
string
required
Required string length: 3
Example:

"XAF"

country
string
required
Required string length: 2
Example:

"CM"

customer
object
required
method
string
required

Code réseau du bénéficiaire

Example:

"mtn_cm"

recipient
object
required
merchant
string<uuid>

UUID du marchand visé. Ignoré pour une clé API (toujours vous-même).

description
string
Example:

"Remboursement commande #778"

metadata
object
fee_charge_mode
enum<string> | null

ADD_ON : les frais s'ajoutent au montant débité au client. DEDUCTED : les frais sont déduits du montant net reversé au marchand. Défaut : configuration du marchand.

Available options:
ADD_ON,
DEDUCTED
preferred_gateway
string

Response

Payout initialisé