Créer un paiement
POST/v1/payments
Crée un paiement, et rend la page à partager avec le payeur.
Le paiement naît « requires_payment » : rien n’est prélevé tant que le payeur n’a pas validé sur son téléphone. Envoyez-lui « payment_url », et attendez le webhook — c’est lui qui dit que l’argent est arrivé. Avec « payer », la demande part aussitôt sur son téléphone : le paiement direct.
Les en-têtes
Idempotency-KeytexteObligatoire avec « payer » : la même clé rend le même paiement, sans relancer le téléphone. Conseillée sinon.
Idempotency-KeytexteObligatoire avec « payer » : la même clé rend le même paiement, sans relancer le téléphone. Conseillée sinon.
Ce qu’on envoie
Un corps JSON. Ce qui n’est pas requis peut être omis.
amountREQUISentierCe qu’on demande au payeur.
currencytexteSans précision : la monnaie de l’espace.
descriptiontexteCe que le payeur lira sur sa page : dites-lui ce qu’il paie.
referencetexteVotre référence, rendue telle quelle.
return_urltexteOù renvoyer le payeur une fois qu’il a payé.
expires_atentierEn secondes depuis 1970.
fees_paid_by« merchant » · « customer »« customer » : les frais s’ajoutent à ce qu’on lui demande.
metadataobjetVos propres clés, rendues telles quelles ; jamais lues par Payiz.
payerobjetLe paiement direct : la demande part aussitôt sur son téléphone. Exige le geste « Paiements · lancer » et un en-tête Idempotency-Key.
amountREQUISentierCe qu’on demande au payeur.
currencytexteSans précision : la monnaie de l’espace.
descriptiontexteCe que le payeur lira sur sa page : dites-lui ce qu’il paie.
referencetexteVotre référence, rendue telle quelle.
return_urltexteOù renvoyer le payeur une fois qu’il a payé.
expires_atentierEn secondes depuis 1970.
fees_paid_by« merchant » · « customer »« customer » : les frais s’ajoutent à ce qu’on lui demande.
metadataobjetVos propres clés, rendues telles quelles ; jamais lues par Payiz.
payerobjetLe paiement direct : la demande part aussitôt sur son téléphone. Exige le geste « Paiements · lancer » et un en-tête Idempotency-Key.
La demande
bash
curl https://api.payiz.app/v1/payments \
-H "Authorization: Bearer sk_test_…" \
-H "Idempotency-Key: paiements-creer-01" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"currency": "XOF",
"description": "Commande 42",
"reference": "cmd-42",
"return_url": "https://boutique.bj/merci"
}'La réponse
json
{
"client_secret": "pcs_01j9x3kq7m4tzv8qhw2n_k3f8",
"object": "payment",
"id": "pay_01j9x3kq7m4tzv8qhw2n",
"amount": 10000,
"currency": "XOF",
"status": "requires_payment",
"description": "Commande 42",
"reference": "cmd-42",
"metadata": {},
"fees_paid_by": "merchant",
"amount_paid": null,
"fee": null,
"net": null,
"amount_refunded": 0,
"payment_url": "https://pay.payiz.app/pay_01j9x3kq7m4tzv8qhw2n",
"return_url": "https://boutique.bj/merci",
"expires_at": 1790089092,
"paid_at": null,
"available_at": null,
"latest_attempt": null,
"created": 1790002692,
"livemode": false
}Ce qu’on reçoit
201 · un objet payment
client_secrettexteLe secret du client, rendu une seule fois à la création : il ouvre le suivi de ce paiement-là depuis le navigateur, sans clé secrète.
object« payment »Le genre de l’objet rendu : il ne change jamais.
idtexteUn identifiant préfixé « pay_ », par exemple pay_01j9x3kq7m4tzv8qhw2n.
amountentierCe qui est demandé au payeur.
currencytexteLe code ISO 4217, en majuscules.
status« requires_payment » · « processing » · « succeeded » · « expired » · « canceled » · « partially_refunded » · « refunded »Où en est le paiement.
descriptiontexte ou nullCe que le payeur lit sur sa page.
referencetexte ou nullVotre propre référence, telle que vous l’avez posée.
metadataobjetCe que vous y avez rangé ; jamais lu par Payiz.
fees_paid_by« merchant » · « customer »Qui porte la commission : le marchand, ou le payeur en plus du montant.
amount_paidentier ou nullCe que le payeur a réellement versé, frais compris.
feeentier ou nullLa commission de Payiz.
netentier ou nullCe qui revient au marchand, commission prise.
amount_refundedentierCe qui a déjà été rendu sur ce paiement.
payment_urltexteLa page à partager avec le payeur.
return_urltexte ou nullOù renvoyer le payeur une fois qu’il a payé.
expires_atentier ou nullDes secondes depuis 1970, ou null.
paid_atentier ou nullDes secondes depuis 1970, ou null.
available_atentier ou nullQuand l’argent devient retirable. Null tant qu’il attend.
latest_attemptobjet ou nullLa dernière demande envoyée au téléphone du payeur, ou null.
createdentier ou nullDes secondes depuis 1970, ou null.
livemodevrai ou fauxFaux en mode test : aucun argent ne circule.
client_secrettexteLe secret du client, rendu une seule fois à la création : il ouvre le suivi de ce paiement-là depuis le navigateur, sans clé secrète.
object« payment »Le genre de l’objet rendu : il ne change jamais.
idtexteUn identifiant préfixé « pay_ », par exemple pay_01j9x3kq7m4tzv8qhw2n.
amountentierCe qui est demandé au payeur.
currencytexteLe code ISO 4217, en majuscules.
status« requires_payment » · « processing » · « succeeded » · « expired » · « canceled » · « partially_refunded » · « refunded »Où en est le paiement.
descriptiontexte ou nullCe que le payeur lit sur sa page.
referencetexte ou nullVotre propre référence, telle que vous l’avez posée.
metadataobjetCe que vous y avez rangé ; jamais lu par Payiz.
fees_paid_by« merchant » · « customer »Qui porte la commission : le marchand, ou le payeur en plus du montant.
amount_paidentier ou nullCe que le payeur a réellement versé, frais compris.
feeentier ou nullLa commission de Payiz.
netentier ou nullCe qui revient au marchand, commission prise.
amount_refundedentierCe qui a déjà été rendu sur ce paiement.
payment_urltexteLa page à partager avec le payeur.
return_urltexte ou nullOù renvoyer le payeur une fois qu’il a payé.
expires_atentier ou nullDes secondes depuis 1970, ou null.
paid_atentier ou nullDes secondes depuis 1970, ou null.
available_atentier ou nullQuand l’argent devient retirable. Null tant qu’il attend.
latest_attemptobjet ou nullLa dernière demande envoyée au téléphone du payeur, ou null.
createdentier ou nullDes secondes depuis 1970, ou null.
livemodevrai ou fauxFaux en mode test : aucun argent ne circule.
© 2026 PayizUne question ? L’aide est dans le rond, en bas à droite.