{
  "slug": "stripe-card-payment-options-declare-saved-card-usage-370ee6ba3394",
  "title": "Stripe card payment options declare saved-card usage",
  "tools": [
    "stripe"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-09-30T00:00:00.000Z",
  "announced_at": "2026-09-30T00:00:00.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "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.",
    "examples": [
      "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\""
    ],
    "gotchas": [
      "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."
    ]
  },
  "why_it_matters": "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.",
  "sources": [
    "https://docs.stripe.com/changelog/endive/2026-09-30/add-card-on-file-usage-indicators",
    "https://docs.stripe.com/payments/cards/save-and-reuse"
  ],
  "rank": 0.95033,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v2+judge-v2x3+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "wave1b-tools-20261017",
    "verdict_id": "wave1b-tools-20261017:wave1b-tools-20261017-4cdb5d3eeebd7b6b-0:gate",
    "evidence_hash": "ea5cb5db7bd56e8c5b318c4d38752400f2f90b41fb88f6e1b7a53443a46a1e8f"
  },
  "review": {
    "draft_hash": "542461856a0013aa1b873155b6cbdbcedbcf6e3341d27766bab769dcf039091d",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "wave1b-tools-20261017:gate",
    "reason": "3 of 3 judge runs approved with p_yes >= 0.9 (mean 0.95 >= 0.9; 2 needed) and Jev gave 0.70 (>= 0.6 needed)."
  }
}