Lancer une demande
POST/v1/payments/{id}/attempts
Envoie la demande sur le téléphone du payeur, ou la relance après un échec.
Le paiement doit attendre d’être payé : une demande en cours répond « attempt_in_progress ». La réponse dit « pending » ; l’issue arrive par webhook. Exige le geste « Paiements · lancer » et un en-tête Idempotency-Key.
Les en-têtes
Idempotency-KeyREQUIStexteObligatoire ici : la même clé rend la même demande, sans relancer le téléphone. Tirez-la de votre commande.
Idempotency-KeyREQUIStexteObligatoire ici : la même clé rend la même demande, sans relancer le téléphone. Tirez-la de votre commande.
Ce qu’on envoie
Un corps JSON. Ce qui n’est pas requis peut être omis.
phoneREQUIStexteLe numéro du payeur, au format international (+2290197000000).
countrytexteSon pays, quand le numéro est écrit sans indicatif.
operatortexteSon opérateur, quand le numéro ne suffit pas à le reconnaître : un code de GET /v1/payment_methods.
phoneREQUIStexteLe numéro du payeur, au format international (+2290197000000).
countrytexteSon pays, quand le numéro est écrit sans indicatif.
operatortexteSon opérateur, quand le numéro ne suffit pas à le reconnaître : un code de GET /v1/payment_methods.
La demande
bash
curl https://api.payiz.app/v1/payments/pay_01j9x3kq7m4tzv8qhw2n/attempts \
-H "Authorization: Bearer sk_test_…" \
-H "Idempotency-Key: paiements-lancer-01" \
-H "Content-Type: application/json" \
-d '{
"phone": "+2290197123456",
"operator": "mtn"
}'La réponse
json
{
"object": "payment_attempt",
"id": "tnt_01j9x4a2b7c5d8e3f6g1h0jk",
"payment": "pay_01j9x3kq7m4tzv8qhw2n",
"status": "pending",
"source": "api",
"phone": "+229 01 •• •• 34 56",
"country": "BEN",
"operator": "mtn",
"amount": 10000,
"currency": "XOF",
"failure_code": null,
"payer_message": "Validez le paiement de 10 000 F CFA sur votre téléphone. Si rien n’arrive, vérifiez votre solde et votre réseau, puis réessayez.",
"operator_reference": null,
"created": 1790002700,
"completed_at": null,
"livemode": false
}Ce qu’on reçoit
201 · un objet payment_attempt
object« payment_attempt »Le genre de l’objet rendu : il ne change jamais.
idtexteUn identifiant préfixé « tnt_ », par exemple tnt_01j9x4a2b7c5d8e3f6g1h0jk.
paymenttexteLe paiement qu’elle cherche à régler.
status« pending » · « succeeded » · « failed » · « expired »« pending » tant que le payeur n’a pas validé ; puis réussie, échouée ou expirée.
source« payer » · « dashboard » · « api »Qui l’a lancée : le payeur sur la page de paiement, votre espace, ou votre serveur par l’API.
phonetexteMasqué : un numéro ne sort jamais en clair.
countrytexteLe pays du payeur, en ISO 3166-1 alpha-3.
operatortexteLe code public de l’opérateur, par exemple « mtn ».
amountentierCe qui est demandé au payeur, dans sa monnaie, frais compris quand il les paie.
currencytexteLa monnaie du payeur, celle de son pays.
failure_code« insufficient_funds » · « payer_declined » · « timeout » · « invalid_phone » · « operator_limit » · « operator_unavailable » · « declined » · « unknown » ou nullLa raison d’un échec ou d’une expiration ; null sinon.
payer_messagetexte ou nullLa phrase à montrer au payeur : la consigne tant qu’il doit valider, la raison si la demande échoue. Réglée par Payiz, dans la langue de « Accept-Language » ; null s’il n’y en a pas.
operator_referencetexte ou nullLa référence que l’opérateur a donnée au payeur, quand il la donne.
createdentier ou nullDes secondes depuis 1970, ou null.
completed_atentier ou nullQuand elle s’est conclue ; null tant qu’elle attend.
livemodevrai ou fauxFaux en mode test : aucun argent ne circule.
object« payment_attempt »Le genre de l’objet rendu : il ne change jamais.
idtexteUn identifiant préfixé « tnt_ », par exemple tnt_01j9x4a2b7c5d8e3f6g1h0jk.
paymenttexteLe paiement qu’elle cherche à régler.
status« pending » · « succeeded » · « failed » · « expired »« pending » tant que le payeur n’a pas validé ; puis réussie, échouée ou expirée.
source« payer » · « dashboard » · « api »Qui l’a lancée : le payeur sur la page de paiement, votre espace, ou votre serveur par l’API.
phonetexteMasqué : un numéro ne sort jamais en clair.
countrytexteLe pays du payeur, en ISO 3166-1 alpha-3.
operatortexteLe code public de l’opérateur, par exemple « mtn ».
amountentierCe qui est demandé au payeur, dans sa monnaie, frais compris quand il les paie.
currencytexteLa monnaie du payeur, celle de son pays.
failure_code« insufficient_funds » · « payer_declined » · « timeout » · « invalid_phone » · « operator_limit » · « operator_unavailable » · « declined » · « unknown » ou nullLa raison d’un échec ou d’une expiration ; null sinon.
payer_messagetexte ou nullLa phrase à montrer au payeur : la consigne tant qu’il doit valider, la raison si la demande échoue. Réglée par Payiz, dans la langue de « Accept-Language » ; null s’il n’y en a pas.
operator_referencetexte ou nullLa référence que l’opérateur a donnée au payeur, quand il la donne.
createdentier ou nullDes secondes depuis 1970, ou null.
completed_atentier ou nullQuand elle s’est conclue ; null tant qu’elle attend.
livemodevrai ou fauxFaux en mode test : aucun argent ne circule.
© 2026 PayizUne question ? L’aide est dans le rond, en bas à droite.