Aller au contenu

Cartes enregistrées et paiements récurrents

Enregistrez une carte lors du premier paiement, proposez le paiement en un clic à vos clients fidèles et débitez les cartes enregistrées pour vos abonnements.

Cardencer peut enregistrer la carte d'un client sur la passerelle au moment du paiement, puis la réutiliser pour accélérer les paiements suivants ou pour des débits effectués en l'absence du client. Vous ne manipulez jamais de numéros de carte : vous conservez uniquement un payment_method_id.

Il existe deux types de réutilisation :

setup_future_usage Usage Qui initie les paiements suivants
on_session Paiement en un clic pour les clients fidèles. Le client, présent, qui peut saisir son CVC.
off_session Abonnements, paiements échelonnés, recharges et autres transactions initiées par le marchand (MIT). Vous, en l'absence du client.

Les cartes enregistrées sont toujours rattachées à un customer_id. Sans customer_id, le paiement est effectué en tant qu'invité et rien n'est enregistré.

Enregistrez une carte lors d'un paiement#

Créez le paiement avec un customer_id et setup_future_usage :

curl https://sandbox.cardencer.com/payments \
  -H "api-key: $CARDENCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1990,
    "currency": "EUR",
    "customer_id": "cus_58211",
    "setup_future_usage": "off_session",
    "description": "Subscription, first month",
    "return_url": "https://example.com/checkout/complete"
  }'

Confirmez-le ensuite avec le SDK de paiement. Le SDK affiche une case « enregistrer la carte » et consigne le consentement du client lorsqu'il la coche. Pour afficher cette case, définissez displaySavedPaymentMethodsCheckbox: true dans les options du payment element.

Lorsque le paiement aboutit, la réponse et le webhook payment_succeeded contiennent le payment_method_id. Associez-le à votre client.

Consentement sans le SDK#

Si vous confirmez depuis votre serveur, vous devez transmettre le consentement du client dans customer_acceptance :

json
{
  "customer_acceptance": {
    "acceptance_type": "online",
    "accepted_at": "2026-11-20T10:15:00Z",
    "online": {
      "ip_address": "203.0.113.10",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/605.1.15"
    }
  }
}

Enregistrez une carte sans débit#

Pour les périodes d'essai gratuites ou la facturation différée, vérifiez la carte avec un paiement d'un montant nul :

curl https://sandbox.cardencer.com/payments \
  -H "api-key: $CARDENCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0,
    "currency": "EUR",
    "confirm": false,
    "customer_id": "cus_58211",
    "payment_type": "setup_mandate",
    "setup_future_usage": "off_session",
    "return_url": "https://example.com/checkout/complete"
  }'

Confirmez-le avec le SDK comme d'habitude. La carte est vérifiée auprès de l'émetteur, rien n'est débité, et vous obtenez un payment_method_id.

Paiement en un clic pour les clients fidèles#

Créez le paiement avec le même customer_id. Le SDK de paiement récupère les cartes enregistrées du client et les affiche au-dessus du formulaire de carte ; le client en choisit une et saisit son CVC si nécessaire.

Sans le SDK, listez les cartes enregistrées depuis votre serveur :

curl https://sandbox.cardencer.com/customers/cus_58211/payment_methods \
  -H "api-key: $CARDENCER_API_KEY"

Chaque entrée comporte un payment_token que vous pouvez transmettre à POST /payments/{payment_id}/confirm.

Débitez une carte enregistrée (à l'initiative du marchand)#

Créez un paiement avec off_session: true et le payment_method_id enregistré dans recurring_details :

curl https://sandbox.cardencer.com/payments \
  -H "api-key: $CARDENCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1990,
    "currency": "EUR",
    "confirm": true,
    "customer_id": "cus_58211",
    "off_session": true,
    "description": "Subscription, month 2",
    "recurring_details": {
      "type": "payment_method_id",
      "data": "pm_lmTnIO5EdCiiOrRqT2RF"
    }
  }'

Cardencer n'est pas un moteur de facturation : c'est vous qui fixez le montant et l'échéancier, et qui appelez l'API à chaque échéance. Si un débit échoue avec un soft decline, invitez le client à revenir en session pour s'authentifier à nouveau.

Fonctionnement de payment_method_id#

Un payment_method_id identifie une carte pour un client donné. Une même carte enregistrée deux fois par le même client correspond au même ID ; une même carte utilisée par deux clients reçoit deux ID distincts.

Client Carte payment_method_id
cus_123 Visa se terminant par 4242 pm_A
cus_123 Mastercard se terminant par 4444 pm_B
cus_456 Visa se terminant par 4242 pm_C

Supprimez une carte enregistrée#

curl -X DELETE https://sandbox.cardencer.com/payment_methods/pm_lmTnIO5EdCiiOrRqT2RF \
  -H "api-key: $CARDENCER_API_KEY"

Permettez à vos clients de supprimer leurs cartes depuis la page de leur compte, et supprimez-les lorsqu'un client clôture son compte.