Skip to main content
POST
Initier un paiement softpay
Testez toujours checkout_url. Quand elle est non vide, votre client ne recevra AUCUNE demande sur son téléphone : vous devez le rediriger vers cette URL, sinon le paiement n’aura jamais lieu.Ce n’est pas un cas marginal — c’est le fonctionnement normal de Wave, Orange Money, Djamo et des cartes bancaires. Un même réseau peut d’ailleurs basculer d’un mode à l’autre sans préavis, selon la route choisie par notre moteur de routage.
return_url sert précisément à ce cas : après paiement sur la page hébergée, votre client y est ramené automatiquement. Sans lui, il reste sur la page du fournisseur.Optionnel pour la quasi-totalité des réseaux (push USSD, pas de page hébergée). Obligatoire pour card/crypto — sans lui, 422 immédiat (return_url manquant), aucun paiement initié. Ces deux réseaux n’ont que la page hébergée, jamais de push : sans URL de retour, votre client n’aurait aucun moyen de revenir chez vous après avoir payé.
Voir Pays, réseaux et format du téléphone pour la liste des codes network valides par pays et le format attendu de customer.phone.

Éviter un doublon en cas de coupure réseau

Le header Idempotency-Key est optionnel : sans lui, chaque appel crée un paiement — un simple retry réseau en pousse donc un second sur le téléphone du client. 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:

"2500.00"

currency
string
required
Required string length: 3
Example:

"XOF"

country
string
required
Required string length: 2
Example:

"BJ"

customer
object
required
network
string
required

Code réseau, cf. référentiel pays/réseaux

Example:

"mtn_bj"

merchant
string<uuid>

UUID du marchand visé. Ignoré pour une clé API (toujours vous-même) ; pour un token dashboard gérant plusieurs marchands, résout la boutique visée si le header X-Merchant-Id n'est pas fourni.

description
string
Example:

"Abonnement mensuel"

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

Code gateway à privilégier si plusieurs sont éligibles pour ce réseau

Response

Paiement poussé avec succès