Enregistrer une carte au premier paiement

Le client consent une fois, et paye en un geste les fois suivantes.

1. Créer le client

Un moyen de paiement appartient à un client. Créez-le avant la session, ou réutilisez son customerId s'il existe déjà. Le client est cloisonné par marchand : son adresse de courriel est unique chez vous, pas chez tout le monde.

post/api/v1/customers

{
  "email": "client@example.com",
  "firstName": "Jean",
  "lastName": "Dupont"
}

2. Demander le consentement à la session

allowCustomerToSavePaymentMethod affiche la case d'enregistrement sur la page de paiement. C'est le client qui coche : vous ne pouvez pas enregistrer une carte à sa place.

post/api/v1/payments/sessions

{
  "order": { "reference": "CMD-001", "amount": 5000, "currency": "XPF" },
  "customerId": "cus_2KmBz9aQp4nT8R",
  "allowCustomerToSavePaymentMethod": true,
  "captureMode": "AUTO",
  "redirectUrl": "https://example.com/return",
  "notificationUrl": "https://example.com/webhook"
}

3. Retrouver la carte enregistrée

GET /api/v1/payment-methods résout le client par customerId, email ou externalId — au moins un est requis. Les cartes supprimées sont exclues.

4. Débiter la carte enregistrée

POST /api/v1/payments/direct encaisse sans page de paiement, sur un moyen de paiement déjà tokenisé.

Un paiement sur carte enregistrée reste soumis aux règles du réseau carte. Un débit non déclenché par le client relève d'un cas d'usage précis, qui n'est pas le simple « il a déjà payé une fois ».