Sessions de paiement

Une session de paiement est une URL à usage unique et de courte durée qui héberge la page de paiement. Vous la créez sur votre serveur, redirigez le client, et vérifiez le résultat au retour. Les données de carte du client ne touchent jamais vos serveurs.

Créer une session de paiement

POST /api/v1/checkout-sessions

Corps de la requête

Champ	Type	Requis	Description
amount	integer	Oui	Montant dans la plus petite unité de la devise (ex. 1000 = 10,00 $)
currency	string	Oui	ISO 4217 : USD, JMD, TTD, BBD, EUR, GYD
success_url	string	Oui	URL de redirection après paiement réussi
failure_url	string	Oui	URL de redirection après paiement échoué
cancel_url	string	Non	URL de redirection pour le bouton Annuler
description	string	Non	Affichée sur la page de paiement et le reçu
customer	object	Non	{name, email}
line_items	array	Non	Détails de commande — voir Lignes, taxes et détails
subtotal	integer	Non	Sous-total avant taxes (centimes)
tax_name	string	Non	Étiquette de taxe (GCT, VAT, Sales Tax)
tax_rate	number	Non	Taux décimal (0.15 = 15 %)
tax_amount	integer	Non	Montant de taxe en centimes
metadata	object	Non	Données arbitraires (renvoyées dans les webhooks)
gateway	string	Non	Slug de passerelle préféré (ex. powertranz_direct)
expires_in_minutes	integer	Non	1–1440. Par défaut 30.

Réponse

{
  "id": "cs_abc123def456",
  "status": "open",
  "amount": 2500,
  "currency": "USD",
  "checkout_url": "https://app.geniuscheckout.com/checkout/cs_abc123def456",
  "expires_at": "2026-05-05T12:30:00+00:00"
}

Redirigez le client vers checkout_url. Il verra la page de paiement à votre marque, le récapitulatif de commande et le formulaire de carte.

Récupérer une session de paiement

GET /api/v1/checkout-sessions/{id}

Vérifiez avant d'expédier

Utilisez ce endpoint pour confirmer le statut du paiement après la redirection du client. Ne faites jamais confiance aux paramètres de l'URL — les URLs de redirection ne contiennent aucune donnée de paiement, juste l'ID de session.

Réponse

{
  "id": "cs_abc123def456",
  "status": "completed",
  "amount": 2500,
  "currency": "USD",
  "description": "Commande #1042",
  "completed_at": "2026-05-05T12:15:00+00:00",
  "transaction": {
    "id": "txn_789xyz",
    "receipt_number": "RCT-000042",
    "status": "captured",
    "card_brand": "Visa",
    "card_last4": "0071",
    "gateway_transaction_id": "5ABCABEC-4867-410B-B76C-E85721CF859B",
    "token_id": "tok_abc123"
  }
}

Statuts de session

Statut	Signification
open	Le client n'a pas encore terminé le paiement
completed	Paiement capturé
failed	Le paiement a été tenté et refusé
expired	Session expirée sans complétion
cancelled	Le client a utilisé le bouton Annuler

Suite

• Flux de paiement — diagramme complet de la création au webhook
• Webhooks — la source autoritative
• Tokenisation et récurrence — réutiliser le token pour les renouvellements