Skip to content

Saved cards & recurring

Save a card on the first payment, offer one-click checkout to returning customers and charge saved cards for subscriptions.

Cardencer can store a customer's card at the gateway when they pay, then reuse it for faster checkouts or for charges made without the customer present. You never handle card numbers: you keep a payment_method_id.

There are two kinds of reuse:

setup_future_usage Use it for Who starts later payments
on_session One-click checkout for returning customers. The customer, who is present and may enter their CVC.
off_session Subscriptions, instalments, top-ups and other merchant-initiated transactions (MIT). You, without the customer present.

Saved cards are always tied to a customer_id. Without one, the payment is a guest checkout and nothing is saved.

Save a card during a payment#

Create the payment with a customer_id and 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"
  }'

Then confirm it with the checkout SDK. The SDK shows a "save card" checkbox and records the customer's consent when they tick it. To show the checkbox, set displaySavedPaymentMethodsCheckbox: true in the payment element options.

When the payment succeeds, the response and the payment_succeeded webhook contain the payment_method_id. Store it against your customer.

If you confirm from your server, you must send the customer's consent in 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"
    }
  }
}

Save a card without charging#

For free trials or delayed billing, verify the card with a zero-amount payment:

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"
  }'

Confirm it with the SDK as usual. The card is checked with the issuer, nothing is charged, and you get a payment_method_id.

One-click checkout for returning customers#

Create the payment with the same customer_id. The checkout SDK fetches the customer's saved cards and shows them above the card form; the customer picks one and enters the CVC if asked.

Without the SDK, list saved cards from your server:

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

Each entry has a payment_token you can pass to POST /payments/{payment_id}/confirm.

Charge a saved card (merchant-initiated)#

Create a payment with off_session: true and the saved payment_method_id in 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 is not a billing engine: you decide the amount and the schedule, and call the API when a charge is due. If a charge fails with a soft decline, bring the customer back on session to re-authenticate.

How payment_method_id works#

A payment_method_id identifies one card for one customer. The same card saved twice by the same customer resolves to the same ID; the same card used by two customers gets two IDs.

Customer Card payment_method_id
cus_123 Visa ending 4242 pm_A
cus_123 Mastercard ending 4444 pm_B
cus_456 Visa ending 4242 pm_C

Remove a saved card#

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

Let customers delete their cards from their account page, and delete them when a customer closes their account.