Stripe card payment options declare saved-card usage
Introduced 2026-09-30 · score 0.95
HOW TO USE IT
When saving a card for future use, set `payment_method_options.card.setup_credential_usage` on a SetupIntent or a PaymentIntent with `setup_future_usage`. When charging a saved card off-session, set `payment_method_options.card.stored_credential_usage` to the usage type for that charge.
curl https://api.stripe.com/v1/setup_intents -u "<YOUR_SECRET_KEY>:" -d "customer=<CUSTOMER_ID>" -d "automatic_payment_methods[enabled]=true" -d "payment_method_options[card][setup_credential_usage]=unscheduled"curl https://api.stripe.com/v1/payment_intents -u "<YOUR_SECRET_KEY>:" -d amount=2000 -d currency=usd -d "customer=<CUSTOMER_ID>" -d "automatic_payment_methods[enabled]=true" -d "payment_method_options[card][setup_credential_usage]=unscheduled"curl https://api.stripe.com/v1/payment_intents -u "<YOUR_SECRET_KEY>:" -d amount=2000 -d currency=usd -d "customer=<CUSTOMER_ID>" -d "payment_method=<PAYMENTMETHOD_ID>" -d off_session=true -d "payment_method_options[card][stored_credential_usage]=unscheduled" -d confirm=true --data-urlencode "return_url=https://example.com/return"WHY THIS HELPS
When implementing saved-card setup or off-session charging that needs a declared credential-on-file usage type, set the corresponding card payment method option.
REQUIREMENTS AND LIMITATIONS
- payment_method_options[card][setup_credential_usage]: Declare the intended future usage type when saving a card with a SetupIntent or a PaymentIntent with `setup_future_usage`. Allowed values: `recurring`, `unscheduled`, `installment`.
- payment_method_options[card][stored_credential_usage]: Declare the usage type for the subsequent charge when charging a saved card. Allowed values: `recurring`, `unscheduled`, `installment`. It can differ from the setup usage type. No mutual exclusivity is documented.
- customer (required): Customer ID for the saved card payment examples.
- amount (required): Amount in the smallest currency unit, shown as `2000` in PaymentIntent examples.
- currency (required): Payment currency, shown as `usd` in PaymentIntent examples.
- payment_method (required): Attached PaymentMethod ID for the saved-card charge.
- off_session (required): Set to `true` for the documented off-session charge.
- confirm (required): Set to `true` in the documented saved-card off-session charge example.
- automatic_payment_methods[enabled]: Set to `true` in the documented card-saving examples.
- Prerequisite: Create the Customer before setting up the card. Create the SetupIntent or PaymentIntent on the server side.
- Prerequisite: For PaymentIntent saving, the customer must opt in to save the card or `setup_future_usage` must be set for `setup_credential_usage` to take effect.
- Existing integrations are not affected unless they adopt these parameters.
- `setup_credential_usage` applies to a Setup Intent or a Payment Intent that uses `setup_future_usage`.
- `stored_credential_usage` is set when charging a saved card off-session.
FIRST-PARTY EVIDENCE
- https://docs.stripe.com/changelog/endive/2026-09-30/add-card-on-file-usage-indicators
- https://docs.stripe.com/payments/cards/save-and-reuse
Check the installed version and the source before using it. Entry JSON