Page de paiement hébergée

Vous créez une session, vous envoyez son URL au payeur. Ni numéro à collecter, ni écran à construire, ni opérateur à choisir.

Quand la préférer à l'API de paiement

POST /v1-payments attend que vous ayez déjà le numéro du payeur et l'opérateur. Le checkout, non : c'est le payeur qui les saisit, sur une page que nous tenons à jour — y compris le jour où un opérateur change son parcours.

Créer

POST /v1-checkout
Authorization: Bearer vp_sk_test_…

{ "amount": 10000, "currency": "XOF",
  "description": "Commande #4821",
  "return_url": "https://votre-site.example/merci" }

{ "id": "cs_…", "object": "checkout_session", "amount": 10000,
  "status": "open", "expires_at": "2026-08-30T14:12:00Z",
  "url": "https://pay.valsoriapay.avasoftware.net/c/tok_…" }

Transmettez url telle quelle. Ne reconstruisez pas ce lien : le jeton qu'il porte n'est pas devinable, et c'est ce qui protège la session.

Ne présumez pas son domaine. Selon votre compte, la page de paiement peut être servie sur un domaine à une autre marque que LibrePay — un réglage que nous posons avec vous. Le lien reste celui que l'API vous rend ; ne le filtrez pas sur un domaine attendu, et ne le réécrivez pas. Un lien émis avant un changement de domaine reste valable : il mène le payeur au bon endroit.

Trois choses à savoir

description est lue par le payeur. Mettez-y votre référence de commande : c'est ce qui lui permet de reconnaître ce qu'il paie, et de vous en parler ensuite. La page n'affiche aucun identifiant interne.

return_url doit être en HTTPS, et le refus est net (invalid_return_url). Un retour en clair exposerait votre référence de commande à tous les intermédiaires réseau.

La session expire. expires_at le dit ; passé ce délai, le lien affiche « demande expirée » plutôt qu'un formulaire mort. Un lien déjà payé ne resservira pas non plus — le repayer rend 409.

Certains opérateurs hébergent leur propre page. Sur Wave, le payeur ne reçoit aucun dialogue sur son téléphone : il doit passer par la page de Wave. La page LibrePay l'y envoie et le ramène ensuite sur elle — vous n'avez rien à faire, et c'est précisément l'intérêt de la page par rapport à l'API de paiement, où cette redirection est à votre charge.

Annuler une session

La commande derrière la session est annulée ? Annulez la session, sinon son lien reste payable jusqu'à expires_at — et l'argent arriverait pour une vente qui n'existe plus.

curl -X POST "$LIBREPAY_BASE/v1-checkout/cs_JBpm7AnJZvBBRHcloKKIfg/cancel" \
  -H "Authorization: Bearer $LIBREPAY_CLE"

Avec l'identifiant cs_… rendu à la création — pas le jeton de l'URL (422 invalid_id).
Seule une session open s'annule. Un paiement en route (processing) ou conclu répond 409 checkout_not_cancellable, avec l'état : « annuler » ne rappellerait pas un débit déjà parti.
Rejouable : annuler une session déjà annulée la rend, sans erreur.
Le payeur qui ouvre le lien lit « demande annulée » ; s'il avait la page ouverte, sa validation est refusée (session_closed).

Dans le SDK : annulerSessionCheckout(id). Depuis la console, le bouton « Annuler » d'un lien fait la même chose.

Suivre le résultat

Comme pour un paiement direct : par webhook. La page se met à jour toute seule côté payeur, mais votre système doit écouter payment.succeeded — l'ouverture de la page ne dit rien du paiement.

La portée de la clé

Le checkout est un encaissement : il exige une clé de portée collect. Une clé de décaissement reçoit 403 insufficient_scope.

Version d'API 2026-08-25 · changements · spécification OpenAPI

Démarrer

API