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"
}'const payment = await fetch("https://sandbox.cardencer.com/payments", {
method: "POST",
headers: { "api-key": process.env.CARDENCER_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
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((r) => r.json());payment = requests.post(
"https://sandbox.cardencer.com/payments",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
json={
"amount": 1990,
"currency": "EUR",
"customer_id": "cus_58211",
"setup_future_usage": "off_session",
"description": "Subscription, first month",
"return_url": "https://example.com/checkout/complete",
},
).json()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.
Consent without the SDK#
If you confirm from your server, you must send the customer's consent in customer_acceptance:
{
"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"
}
}'const charge = await fetch("https://sandbox.cardencer.com/payments", {
method: "POST",
headers: { "api-key": process.env.CARDENCER_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
amount: 1990,
currency: "EUR",
confirm: true,
customer_id: "cus_58211",
off_session: true,
description: "Subscription, month 2",
recurring_details: { type: "payment_method_id", data: savedPaymentMethodId },
}),
}).then((r) => r.json());charge = requests.post(
"https://sandbox.cardencer.com/payments",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
json={
"amount": 1990,
"currency": "EUR",
"confirm": True,
"customer_id": "cus_58211",
"off_session": True,
"description": "Subscription, month 2",
"recurring_details": {"type": "payment_method_id", "data": saved_payment_method_id},
},
).json()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.