--- schema_version: 1 route: /t/stripe.md tool: "stripe" --- # sincecutoff.com /t/stripe — Stripe API - name: Stripe API - kind: api - children: none - homepage: Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows. Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json). To stay current, read the changes feed: [`/v1/changes.md?tool=stripe`](https://sincecutoff.com/v1/changes.md?tool=stripe) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt). ### GB bank account payout method payments eligibility no longer waits on Confirmation of Payee (2026-09-30) - slug: gb-bank-account-payout-method-payments-eligibility-no-longer-waits-on-confirmati-084238929e82 - score: 0.95 How to use it: When handling a GB bank account payout method on API version `2026-09-30.preview`, treat `usage_status.payments: eligible` as payment eligible and stop waiting for `confirmation_of_payee` or an Outbound Setup Intent `requires_action`. - why_it_matters: Update GB bank account payout handling that waits for payment eligibility or Outbound Setup Intent completion. - before: Previously, GB bank account payout methods reported `usage_status.payments = requires_action` with a `confirmation_of_payee` next action, and their Outbound Setup Intents resolved to `requires_action`. - sources: , - gotchas: "Version: 2026-09-30.preview"; "usage_status.payments: Payment eligibility status; the object page documents `usage_status` as indicating requirements for outbound money movement. The versioned change specifies that GB bank accounts report `eligible` from `2026-09-30.preview`."; "usage_status.transfers: Transfer eligibility status; unchanged by this change."; "Confirmation of Payee may still be required before the payout method can be used to receive payouts."; "`usage_status.transfers` is unchanged." ### Stripe Accounts v2 adds the satispay_payments capability (2026-09-30) - slug: stripe-accounts-v2-adds-the-satispay-payments-capability-ca54090a9d6a - score: 0.98 How to use it: If an Accounts v2 integration needs to accept Satispay payments, set `configuration.merchant.capabilities.satispay_payments.requested` to `true` when creating or updating the v2 Account. Read `status` and `status_details` for the capability state and context. Examples: ``` POST /v2/core/accounts {"configuration":{"merchant":{"capabilities":{"satispay_payments":{"requested":true}}}}} ``` ``` POST /v2/core/accounts/ {"configuration":{"merchant":{"capabilities":{"satispay_payments":{"requested":true}}}}} ``` - why_it_matters: For an integration using Accounts v2 that needs to accept Satispay payments, request the capability on the v2 Account. - before: Configure Satispay separately instead of requesting the capability directly on the v2 Account. - sources: - gotchas: "satispay_payments.requested (required): Set to `true` to request the capability."; "satispay_payments.status: Reports whether Satispay payments are active, pending, restricted, or unsupported for the account."; "satispay_payments.status_details: Array with additional context about capability status."; "Prerequisite: The integration uses Accounts v2."; "Applies to integrations using Accounts v2 that want to accept Satispay payments."; "The capability status can be active, pending, restricted, or unsupported for the account." ### Stripe Activity Logs API adds action groups and investigation context (2026-09-30) - slug: stripe-activity-logs-api-adds-action-groups-and-investigation-context-c4e593454d01 - score: 0.93 How to use it: When investigating account security, authentication, payout, or Issuing changes, list Activity Logs filtered to the relevant action groups. Inspect each entry’s type and details, plus actor, related_object, and request for investigation context. Examples: ``` curl https://api.stripe.com/v2/iam/activity_logs?action_groups[]= -H "Authorization: Bearer " -H "Stripe-Version: 2026-09-30.preview" -H "Stripe-Context: " ``` ``` curl https://api.stripe.com/v2/iam/activity_logs -H "Authorization: Bearer " -H "Stripe-Version: 2026-09-30.preview" -H "Stripe-Context: " ``` - why_it_matters: Inspect authentication, security, payout, or Issuing changes recorded in Activity Logs and filter entries for the relevant action groups. - sources: , , - gotchas: "Availability: Activity Logs API version 2026-09-30.preview"; "action_groups: Array filter for activity log action groups. Documented values relevant here: sso, scim, user_profile, account_security, authentication, payout, issuing."; "type: Response enum identifying the action performed."; "details: Response object containing action-specific details."; "actor: Response object identifying the actor that performed the action."; "related_object: Nullable response object for the object related to the activity log entry."; "request: Nullable response object for the API request that instigated the action." ### Stripe Balance Transactions add Issuing provisional credit types (2026-09-30) - slug: stripe-balance-transactions-add-issuing-provisional-credit-types-b2769d7669c7 - score: 0.94 How to use it: If your integration filters or processes Balance Transaction `type` values, handle `issuing_dispute_provisional_credit` and `issuing_dispute_provisional_credit_reversal`. Use those types to distinguish provisional credit movements during reconciliation, and review Balance Reports that use `reporting_category`. Examples: ``` curl -G https://api.stripe.com/v1/balance_transactions -u ":" -d "type=issuing_dispute_provisional_credit" ``` ``` curl -G https://api.stripe.com/v1/balance_transactions -u ":" -d "type=issuing_dispute_provisional_credit_reversal" ``` - why_it_matters: Update an integration that filters or processes Stripe Balance Transactions by type to handle provisional credits for Issuing disputes. - sources: , , - gotchas: "type: Filters the list to transactions of the given type; the release note adds the two provisional-credit values listed above."; "reporting_category: Balance Transaction categorization used by Balance Reports; the two new values each have a corresponding category for differentiation."; "The new values concern money movement related to provisional credits for Issuing disputes."; "The existing `issuing_dispute` type continues to represent the final credit for a won dispute."; "Both new values are available as filters when listing Balance Transactions."; "Each new type has a corresponding `reporting_category` for differentiation in Balance Reports."; "The values also appear in SDK type definitions and OpenAPI specs."; "Docs conflict: The accessible current API reference omits the two new types from its documented enum, although the release note for API version 2026-09-30.endive states they are valid list filters. Used the release note for those values; do not rely on the current enum list." ### Stripe Billing Feedback Options API adds custom subscription cancellation reasons (2026-09-30) - slug: stripe-billing-feedback-options-api-adds-custom-subscription-cancellation-reason-f16ab79b6f21 - score: 0.95 How to use it: When configuring portal cancellation feedback, set the cancellation feature and its documented reason settings on the customer portal configuration. The available documentation does not show how to attach Billing Feedback Option resources. Examples: ``` curl https://api.stripe.com/v1/billing_portal/configurations/ -u ":" --data-urlencode "features[subscription_cancel][cancellation_reason][enabled]=true" ``` - why_it_matters: Configure custom cancellation reasons for a subscription customer portal cancellation flow. - sources: , - gotchas: "Version: 2026-09-30.endive"; "features (required): Portal configuration features object."; "features.subscription_cancel.cancellation_reason.enabled (required): Whether cancellation reasons are collected in the portal."; "features.subscription_cancel.cancellation_reason.options (required): Documented as an array of enums; the page does not document custom feedback-option resource IDs."; "The feedback options are presented to customers canceling through the customer portal."; "Docs conflict: The accessible configuration reference documents cancellation_reason.options as enum values (too_expensive, missing_features, switched_service, unused, other), not Billing Feedback Option resource IDs; it does not establish the custom-resource configuration described in the release note."; "Docs conflict: The accessible configuration reference does not carry the stated 2026-09-30.endive API version." ### Stripe card payment options declare saved-card usage (2026-09-30) - slug: stripe-card-payment-options-declare-saved-card-usage-370ee6ba3394 - 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. Examples: ``` curl https://api.stripe.com/v1/setup_intents -u ":" -d "customer=" -d "automatic_payment_methods[enabled]=true" -d "payment_method_options[card][setup_credential_usage]=unscheduled" ``` ``` curl https://api.stripe.com/v1/payment_intents -u ":" -d amount=2000 -d currency=usd -d "customer=" -d "automatic_payment_methods[enabled]=true" -d "payment_method_options[card][setup_credential_usage]=unscheduled" ``` ``` curl https://api.stripe.com/v1/payment_intents -u ":" -d amount=2000 -d currency=usd -d "customer=" -d "payment_method=" -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_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: , - 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." ### Stripe Charge expansion supports payment_method_details.card.mandate (2026-09-30) - slug: stripe-charge-expansion-supports-payment-method-details-card-mandate-a47c4b2f382d - score: 0.98 How to use it: For a Charge on a card payment with an associated mandate, retrieve the Charge with `expand[]=payment_method_details.card.mandate` to include the full Mandate object in the response. Without expansion, the field is the mandate ID when present, or `null`. Examples: ``` curl -G https://api.stripe.com/v1/charges/ \ -u ":" \ -d "expand[]=payment_method_details.card.mandate" ``` - why_it_matters: When retrieving a Charge for a card payment with an associated mandate, include the mandate details in the same API response. - before: Previously, the property returned the mandate ID when present; the release note does not state the prior retrieval procedure. - sources: , - gotchas: "expand[] = payment_method_details.card.mandate: Expands the card mandate property to its full Mandate object. The release note names this value; Stripe’s expansion guide documents `expand[]` and dot notation for nested expansions."; "CHARGE_ID (required): Placeholder for the Charge identifier in the retrieve URL. The exact retrieve command was not available in the official docs accessed."; "YOUR_SECRET_KEY (required): Placeholder for the Stripe secret API key used for authentication in the documented curl expansion pattern."; "Applies to card payments with an associated mandate." ### Stripe Checkout Sessions removes `payment_method_types` on creation (2026-09-30) - slug: stripe-checkout-sessions-removes-payment-method-types-on-creation-2563620951b1 - score: 0.97 How to use it: If creating Checkout Sessions with `payment_method_types`, remove that parameter because it now returns HTTP 400. Use Dashboard-managed dynamic payment methods, or set `allowed_payment_method_types` to filter compatible methods; use `excluded_payment_method_types` to exclude methods. Examples: ``` curl https://api.stripe.com/v1/checkout/sessions \ -u : \ -d success_url="https://example.com/success" \ -d "line_items[0][price]"= \ -d "line_items[0][quantity]"=2 \ -d mode=payment ``` - why_it_matters: Update an integration that creates Checkout Sessions with `payment_method_types` to use the supported payment method configuration. - before: Pass `payment_method_types` when creating a Checkout Session; specifying an incompatible payment method returned an error. - sources: , - gotchas: "Version: 2026-09-30.endive"; "payment_method_types: Removed from Checkout Session creation; including it returns HTTP 400."; "allowed_payment_method_types: Array of payment method types; filters to methods compatible with parameters such as currency, amount, and customer. The compatible subset appears in the response’s `payment_method_types` property."; "excluded_payment_method_types: Excludes specific payment methods from dynamic payment method results. The create API parameter details were inaccessible, so its accepted values and exact syntax were not verified."; "Prerequisite: Dynamic payment methods can be configured in the Stripe Dashboard; only enabled methods can be shown to customers."; "Passing `payment_method_types` when creating a Checkout Session now returns a `400` error."; "`allowed_payment_method_types` accepts an array of payment method types and filters the list to methods compatible with other parameters such as `currency`, `amount`, and `customer`." ### Stripe Checkout Sessions update payment_intent_data in payment mode (2026-09-30) - slug: stripe-checkout-sessions-update-payment-intent-data-in-payment-mode-2ea60877782b - score: 0.96 How to use it: For an active Checkout Session in payment mode using `ui_mode=elements`, update it with `payment_intent_data` before confirming payment. Set the documented PaymentIntent fields there to change them without recreating the session. - why_it_matters: When updating PaymentIntent settings for an active Checkout Session in payment mode, modify them before confirming payment without recreating the session. - sources: , - gotchas: "payment_intent_data: Nested PaymentIntent configuration passed when updating the Checkout Session. The current update reference available here does not document this parameter; the release note says it is accepted for this change."; "description: Arbitrary string attached to the PaymentIntent."; "metadata: Key-value pairs attached to the PaymentIntent; individual keys or all keys can be unset with empty values."; "setup_future_usage: Controls whether the payment method is intended for reuse; allowed values documented on the PaymentIntent update page are `on_session` and `off_session`."; "statement_descriptor: Statement text for a non-card charge; setting it for a card charge returns an error."; "statement_descriptor_suffix: Not documented in the official PaymentIntent update reference page available here."; "ui_mode=elements (required): Required by the release note for this update capability."; "mode=payment (required): Checkout Session mode must be `payment`."; "active state; update before confirmation (required): The release note requires the Checkout Session to be active and the update to occur before payment confirmation."; "Prerequisite: The release note identifies this capability in the 2026-09-30.preview API version; the versioned update reference was inaccessible, so specific setup or preview-access requirements were not confirmed."; "The Checkout Session must use `ui_mode=elements` and be in an active state."; "The session must be in payment mode."; "Update the PaymentIntent configuration before confirming the payment."; "Docs conflict: The currently accessible unversioned Checkout Session update reference documents `metadata`, `collected_information`, and `shipping_options`, but not `payment_intent_data`; it may reflect an older API version, so it does not establish behavior for 2026-09-30.preview. https://docs.stripe.com/api/checkout/sessions/update" ### Stripe customer portal sessions support recovery after expiration (2026-09-30) - slug: stripe-customer-portal-sessions-support-recovery-after-expiration-55cf232d23f7 - score: 0.96 How to use it: When creating a portal session that should be recoverable after expiration, set `after_expiration[type]` to `customer_login`. Customers can verify their email and receive a replacement session using the original URL; set `after_expiration[customer_login][expires_at]` to limit recovery. Examples: ``` curl https://api.stripe.com/v1/billing_portal/sessions \ -u ":" \ -H "Stripe-Version: 2026-09-30.preview" \ -d "customer=" \ --data-urlencode "return_url=https://example.com/account" \ -d "after_expiration[type]"=customer_login ``` ``` curl https://api.stripe.com/v1/billing_portal/sessions \ -u ":" \ -H "Stripe-Version: 2026-09-30.preview" \ -d "customer=" \ --data-urlencode "return_url=https://example.com/account" \ -d "after_expiration[type]"=customer_login \ -d "after_expiration[customer_login][expires_at]"= ``` - why_it_matters: Let customers reopen the customer portal from an existing session URL after that session expires. - sources: , , - gotchas: "Availability: API version 2026-09-30.preview"; "customer (required): ID of an existing customer."; "return_url: Redirect destination when the customer returns to your site; required if no default return URL is set in the Dashboard configuration."; "after_expiration: Set when creating each portal session to configure behavior after expiration."; "after_expiration.type (required): Set to `customer_login` to allow customers to verify their email and receive a replacement session with the same configuration."; "after_expiration.customer_login.expires_at: Timestamp deadline for recovery. If omitted, recovery is available at any time after the session expires."; "Prerequisite: Create a customer before creating the portal session."; "Prerequisite: Authenticate customers on your site before creating sessions for them."; "Prerequisite: Use the customer ID and a `return_url`; `return_url` is required when the Dashboard configuration has no default return URL."; "Session recovery is enabled by setting `after_expiration` when creating each portal session."; "If `expires_at` is omitted, customers can recover the session at any time after it expires." ### Stripe Subscription updates support cancel_at_period_end in pending updates (2026-09-30) - slug: stripe-subscription-updates-support-cancel-at-period-end-in-pending-updates-5a83f430205f - score: 0.93 How to use it: When an update should cancel a subscription at the current period end after payment succeeds, update it with `payment_behavior=pending_if_incomplete` and `cancel_at_period_end=true`. Stripe stores the setting in `pending_update` if payment fails or requires customer action; a conflicting later cancellation value expires the pending update. Examples: ``` curl https://api.stripe.com/v1/subscriptions/ \ -u ":" \ -d payment_behavior=pending_if_incomplete \ -d proration_behavior=always_invoice \ -d "items[0][id]=" \ -d "items[0][price]=" \ -d cancel_at_period_end=true ``` - why_it_matters: When scheduling an incomplete Subscription update that should also cancel at the billing period end, set cancel_at_period_end as part of the pending update. - before: Before this change, passing `cancel_at_period_end` with `payment_behavior=pending_if_incomplete` returned an error. - sources: , , - gotchas: "subscription_id (required): Subscription ID in the update URL."; "payment_behavior (required): Set to `pending_if_incomplete` to use pending updates."; "cancel_at_period_end (required): Set to `true` to cancel at the current period end; supported for pending updates."; "proration_behavior: `always_invoice` creates an invoice and attempts payment when the update is made."; "items[0][id]: Subscription item ID to update; included in the documented example."; "items[0][price]: Price ID to apply to the subscription item; included in the documented example."; "Prerequisite: Pending updates require `collection_method=charge_automatically` and a supported payment method."; "Prerequisite: The update must generate an invoice to trigger a pending update; `proration_behavior=always_invoice` does so in the documented example."; "Prerequisite: Authenticate the API request with a Stripe secret key."; "cancel_at_period_end is a nullable boolean property of pending_update on a Subscription."; "The cancellation takes effect at the end of the current billing period after the pending update applies."; "A conflicting cancel_at_period_end value in a subsequent update expires the existing pending update." ### Stripe Subscriptions can be paused and resumed on demand (2026-09-30) - slug: stripe-subscriptions-can-be-paused-and-resumed-on-demand-18253f992aab - score: 0.95 How to use it: When pausing or resuming a subscription, use flexible billing mode and handle its paused status and pause/resume events to update service access. Stripe’s versioned pause and resume API details, including the new fields, were not accessible in the documentation search. Examples: ``` curl https://api.stripe.com/v1/subscriptions//resume \ -u ":" \ -d billing_cycle_anchor=now ``` - why_it_matters: When implementing subscription lifecycle handling, pause and resume a subscription and update service access based on subscription events. - sources: , , , , - gotchas: "Version: 2026-09-30.endive"; "billing_cycle_anchor: Resume-time billing cycle anchor: `now` or `unchanged`; defaults to `now`."; "status: Subscription status may be `paused`. The current object reference does not document `status_details`."; "customer.subscription.paused: Event emitted when a subscription enters `status=paused`; not when payment collection is paused."; "customer.subscription.resumed: Event emitted when a subscription is no longer paused; not when payment collection resumes."; "Prerequisite: Flexible billing mode requires Stripe API version `2025-06-30.basil` or later. API-created subscriptions use flexible mode by default on `2025-09-30.clover` or later; otherwise set the billing mode explicitly or migrate existing subscriptions."; "Prerequisite: The Subscription reference says a paused subscription does not generate invoices; pausing payment collection leaves status unchanged and still generates invoices."; "Flexible billing mode must be enabled to pause a subscription."; "Pausing a subscription stops invoice generation; pausing payment collection instead continues invoice generation but pauses payment collection."; "Docs conflict: Current subscription object reference says a subscription can only enter `paused` when a trial ends without a payment method. The release note describes on-demand pausing; this reference may predate the stated release version, so it does not establish the new behavior." ### Trial Offers support archiving and trial end settings (2026-09-30) - slug: trial-offers-support-archiving-and-trial-end-settings-487620f4dbda - score: 0.91 How to use it: To retire a trial offer, set `active=false` when creating or updating it. For subscription trial-end behavior, set `trial_settings` to configure the missing-payment-method action and billing-cycle anchor. Examples: ``` curl https://api.stripe.com/v1/product_catalog/trial_offers/ \ -u "" \ -H "Stripe-Version: 2026-09-30.preview" \ -d active=false ``` ``` curl https://api.stripe.com/v1/subscriptions \ -u "" \ -H "Stripe-Version: 2026-09-30.preview" \ -d customer= \ -d "items[0][price]=" \ -d "trial_settings[end_behavior][missing_payment_method]=pause" \ -d "trial_settings[end_behavior][billing_cycle_anchor]=unchanged" ``` - why_it_matters: Retire an outdated trial offer while preserving subscriptions already using it, or configure what happens when a trial ends. - before: For missing-payment-method behavior, use subscription-level free trials; trial offers did not support those options. The source doesn't state the prior archiving behavior or prior billing cycle anchor behavior. - sources: , , - gotchas: "active: Boolean; whether the trial offer can be used for new purchases. Set to `false` to archive it."; "trial_settings.end_behavior.missing_payment_method: At trial end without a payment method, choose `create_invoice`, `pause`, or `cancel`."; "trial_settings.end_behavior.billing_cycle_anchor: The release note describes `unchanged` as preserving the existing billing cycle and creating a prorated post-trial period."; "end_behavior.type: Use this property to determine the trial offer’s end behavior."; "end_behavior.transition: Optional property; it is no longer returned on all responses."; "customer: Identifier of the customer to subscribe."; "items (required): List of up to 20 subscription items, each with an attached price."; "Prerequisite: The subscription-create reference lists prerequisite setup: create a payment method, create a customer and attach it, create a product, and create a price."; "Prerequisite: Requests use a Stripe secret key and the `2026-09-30.preview` API version."; "Archived offers can't be attached to new subscription items; existing subscriptions continue using the trial offer until their trial ends."; "Missing-payment-method settings apply when a trial ends naturally or when the trial is ended early by changing or removing the trialing item." ### Stripe billing portal sessions support the customer_update deep link (2026-08-26) - slug: stripe-billing-portal-sessions-support-the-customer-update-deep-link-0cd514f14ecf - score: 0.97 How to use it: When creating a billing portal session for customer detail updates, set `flow_data.type` to `customer_update` to link directly to the billing information page. Examples: ``` curl https://api.stripe.com/v1/billing_portal/sessions \ -u "" \ -H "Stripe-Version: 2026-08-26.dahlia" \ -d customer= \ -d "flow_data[type]"=customer_update ``` - why_it_matters: When implementing a billing portal flow that lets customers update their billing details, create a session that links directly to the billing information page. - sources: , - gotchas: "customer: ID of an existing customer; the request example uses it to identify the customer."; "flow_data: Information about a specific flow for the customer to go through."; "flow_data.type: Set to `customer_update` for a direct link to the billing information page. The release note documents `customer_update` alongside `payment_method_update`, `subscription_cancel`, and `subscription_update` as flow types."; "Prerequisite: Create a customer first; the session API reference lists `createCustomer` as a prerequisite." ### Stripe Checkout Sessions restrict card funding types (2026-08-26) - slug: stripe-checkout-sessions-restrict-card-funding-types-af4ffa6bbf17 - score: 0.96 How to use it: When creating a Checkout Session, set `payment_method_options.card.restrictions.funding_types_blocked` to block specified card types; Stripe says a customer attempting to use a restricted type sees an error. Examples: ``` curl https://api.stripe.com/v1/checkout/sessions \ -u ":" \ -H "Stripe-Version: 2026-08-26.dahlia" \ --data-urlencode success_url="" \ -d "line_items[0][price]"="" \ -d "line_items[0][quantity]"=1 \ -d mode=payment \ -d "payment_method_options[card][restrictions][funding_types_blocked][]"=prepaid ``` - why_it_matters: When implementing checkout payment restrictions, configure a Checkout Session to block specified card funding types. - sources: , - gotchas: "payment_method_options[card][restrictions][funding_types_blocked]: List of card funding types to block: `credit`, `debit`, and/or `prepaid`. The release note documents the setting and allowed values; create-session request example documents the other required fields shown."; "mode (required): Checkout Session mode; `payment` accepts one-time payments."; "line_items (required): List of items being purchased; required for `payment` and `subscription` mode."; "success_url: Redirect URL after payment or setup; required for embedded or custom UI mode when redirect-based payment methods are enabled, and disallowed for those UI modes."; "Prerequisite: To use this parameter, requests must use API version `2026-08-26.dahlia` (or the corresponding SDK/API version upgrade); the Stripe changelog says to set the `Stripe-Version` header for REST requests."; "Applies to Checkout Sessions."; "Restricted card funding types cause the Checkout Session to show an error." ### Stripe Confirmation Tokens support metadata (2026-08-26) - slug: stripe-confirmation-tokens-support-metadata-a5f6c07118b5 - score: 0.94 How to use it: When an Elements payment flow creates a ConfirmationToken for server-side confirmation, call `stripe.createConfirmationToken` with metadata in `params`; then retrieve the token server-side with your secret key and read `metadata`. Examples: ``` const {confirmationToken, error} = await stripe.createConfirmationToken({elements, params: {metadata: {order_id: ""}}}); ``` ``` stripe.confirmationTokens.retrieve("") ``` - why_it_matters: When implementing a payment flow that creates and retrieves Confirmation Tokens, attach metadata and read it on the server. - sources: , , , - gotchas: "Version: 2026-08-26.dahlia"; "elements (required): Elements instance used to create the Express Checkout Element or Payment Element; `stripe.createConfirmationToken` collects payment, billing, and shipping details from it."; "params: Parameters passed to the Stripe API; may include `metadata`."; "params.metadata: Map of key-value pairs attached to the ConfirmationToken; supports up to 50 pairs. Metadata is not returned in the frontend response."; "metadata: Nullable map of key-value pairs on a ConfirmationToken object."; "Prerequisite: Use the Elements instance associated with an Express Checkout Element or Payment Element."; "Prerequisite: Retrieving the token and its metadata is described for server-side use with a secret key."; "Metadata can be attached when creating a ConfirmationToken through Stripe.js."; "Up to 50 key-value pairs are supported."; "Retrieval with metadata is described for server-side use with a secret key." ### Stripe Customer Sessions query entitlements and open customer portal (2026-08-26) - slug: stripe-customer-sessions-query-entitlements-and-open-customer-portal-47269324db93 - score: 0.97 How to use it: For subscription access and billing management in an iOS app, create a Customer Session for the authenticated user with `active_entitlements` and/or `customer_portal` enabled. Return its `client_secret` to the app, then use BillingSDK to check entitlements or present the portal. Examples: ``` const customerSession = await stripe.customerSessions.create({ customer: "", components: { active_entitlements: { enabled: true }, customer_portal: { enabled: true } } }); res.json({ clientSecret: customerSession.client_secret }); ``` ``` let entitlements = try await BillingManager.shared.billing.getActiveEntitlements(forceRefresh: true) ``` ``` let portal = try await BillingManager.shared.billing.getCustomerPortal() portal.presentCustomerPortal(from: self) ``` - why_it_matters: When implementing subscription access and billing management in an application, enable the relevant Customer Session components and use the session client secret in the client. - sources: , - gotchas: "customer (required): Stripe Customer ID for the authenticated user."; "components.active_entitlements.enabled: Set to `true` to enable active entitlement retrieval for the Customer Session."; "components.customer_portal.enabled: Set to `true` to enable customer portal access for the Customer Session."; "components.active_entitlements: Enables the active entitlements component; can be enabled together with `customer_portal`."; "components.customer_portal: Enables the customer portal component; can be enabled together with `active_entitlements`."; "client_secret (required): Customer Session secret returned by the server and used by the client SDK to authenticate."; "forceRefresh: When true, forces an entitlement refresh to obtain the latest data from the server."; "Prerequisite: Use Stripe API version `2026-08-26.dahlia` or later for the iOS BillingSDK flow."; "Prerequisite: Provide a backend server to create Customer Sessions; the iOS guide also requires iOS 15+, macOS 12+, and Xcode 15+."; "Prerequisite: The customer portal requires an active authenticated session."; "These components don't change the behavior of the Payment Element." ### Stripe Payment Link update accepts Connect parameters (2026-08-26) - slug: stripe-payment-link-update-accepts-connect-parameters-24cc6f966411 - score: 0.94 How to use it: When updating a Payment Link used with Connect, send the supported money movement parameters to update its settings for future Checkout Sessions. Existing active sessions are unaffected. Examples: ``` curl https://api.stripe.com/v1/payment_links/ \ -u ":" \ -H "Stripe-Version: 2026-08-26.dahlia" \ -d "application_fee_amount=" \ -d "application_fee_percent=" \ -d "on_behalf_of=" \ -d "transfer_data[destination]=" ``` ``` curl https://api.stripe.com/v1/payment_links/ \ -u ":" \ -H "Stripe-Version: 2026-08-26.dahlia" \ -d "application_fee_amount=" ``` - why_it_matters: For a repository workflow that updates an existing Payment Link's Connect money movement configuration, modify the link and apply the updated settings to future Checkout Sessions. - before: These parameters were previously available only when creating a Payment Link. - sources: , - gotchas: "Version: 2026-08-26.dahlia"; " (required): ID of the Payment Link to update."; "application_fee_amount: Integer fee amount transferred to the application owner; only when no line item has a recurring price. Empty string unsets it."; "application_fee_percent: Non-negative percentage from 0 to 100, at most two decimals; requires at least one recurring-price line item. Empty string unsets it."; "on_behalf_of: Account on whose behalf to charge. Empty string unsets it."; "transfer_data: Object specifying the account, if any, to which payments are attributed for tax reporting and where funds are transferred. Empty string unsets it; documented subkeys not found."; "Prerequisite: The update API reference lists a Price and an existing Payment Link as prerequisite objects; create a Price and Payment Link first if they do not already exist."; "Prerequisite: The changelog says REST API requests must specify Stripe-Version: 2026-08-26.dahlia to use this API version."; "Applies to Payment Links used with Connect."; "The updated configuration affects Checkout Sessions created from the Payment Link after the change; existing active sessions are unaffected." ### Stripe Signals APIs add account activity, evaluations, and risk-signal lookup (2026-08-26) - slug: stripe-signals-apis-add-account-activity-evaluations-and-risk-signal-lookup-a961690aac5a - score: 0.98 How to use it: When integrating account abuse risk decisions with Stripe, submit activity, request evaluations for `user_account_sharing` and `user_multi_accounting`, and use completed evaluation signals to guide a decision; report the outcome and list or retrieve account signals. Exact operation parameters were not accessible in the official docs I could read. Examples: ``` Not found: complete runnable Account Activity and Account Evaluation requests for this task. ``` - why_it_matters: For a coding workflow that integrates account-abuse risk decisions with Stripe, submit account activity, request evaluations, and retrieve their signals. - sources: , - gotchas: "Availability: public preview"; "Prerequisite: The release note describes these APIs as public preview. The readable Account Signals page says terminal docs require Stripe CLI v1.43.3+ and points to CLI installation." ### Stripe v2 Payout Methods can be disabled for outbound money movement (2026-08-26) - slug: stripe-v2-payout-methods-can-be-disabled-for-outbound-money-movement-b88a4cb8ffc9 - score: 0.90 How to use it: When processing v2 Payout Methods for payments or transfers, handle `usage_status` values including `disabled`. To stop outbound use, disable the Payout Method; to re-enable it, create a new Outbound Setup Intent. - why_it_matters: When maintaining an integration that uses v2 Payout Methods for outbound payments or transfers, handle payout methods whose usage_status is disabled. - sources: , , - gotchas: "usage_status: Object indicating whether the Payout Method meets requirements for outbound money movement. The retrieved object example shows `payments` and `transfers` values as `eligible`. The docs page did not expose the allowed values for these sub-keys."; "Payout Method disable endpoint (required): `POST /v2/money_management/payout_methods/:id/disable`; endpoint parameters and runnable example were not accessible in the official docs page."; "A disabled payout method is unavailable for outbound money movement."; "The disabled status is non-terminal; re-enabling requires creating a new Outbound Setup Intent."; "Integrations that do not handle usage_status=disabled for payments and transfers might experience unexpected failures." ### Reject connected accounts with non-zero balances and control payout pausing (2026-07-29) - slug: reject-connected-accounts-with-non-zero-balances-and-control-payout-pausing-d349c84c2274 - score: 0.95 How to use it: When rejecting a connected account, call the Reject an account endpoint; for accounts with any balance, use `payouts_action=none` to keep payouts enabled, or omit it to use the default `pause` behavior. Examples: ``` curl https://api.stripe.com/v1/accounts//reject \ -u ":" \ -d reason=fraud \ -d payouts_action=none ``` ``` curl https://api.stripe.com/v1/accounts//reject \ -u ":" \ -d reason=fraud ``` - why_it_matters: When maintaining an integration that rejects connected accounts, reject an account with a non-zero balance or keep payouts enabled after rejection. - before: Before the change, rejecting an account with a non-zero balance returned an error, and payouts were always paused during rejection. - sources: , - gotchas: "account_id (required): Account ID in the endpoint path."; "reason (required): Reason for rejection: `fraud`, `terms_of_service`, or `other`."; "payouts_action: `pause` (default) pauses payouts during rejection; `none` leaves payouts enabled."; "Prerequisite: Reject is available for connected accounts where the platform is liable for negative balances, including Custom and Express accounts. The API reference says test-mode accounts can be rejected at any time."; "Prerequisite: Authenticate the request with a Stripe secret key."; "Docs conflict: The API reference available to search says live-mode accounts can only be rejected after all balances are zero and only documents `reason`; this conflicts with the 2026-07-29 Dahlia release note. The endpoint page could not be accessed with the Dahlia version parameter, so those older reference details are not applied here." ### Stripe API adds Unreject an account for platform-initiated rejections (2026-07-29) - slug: stripe-api-adds-unreject-an-account-for-platform-initiated-rejections-cb058767a8c0 - score: 0.98 How to use it: If a connected account is currently rejected by your platform, POST to the unreject endpoint to reverse that rejection. This re-enables charges and payouts only when no separate restrictions remain, and reverts the account’s application state. Examples: ``` curl -X POST https://api.stripe.com/v1/accounts//unreject \ -u "" \ -H "Stripe-Version: 2026-07-29.dahlia" ``` - why_it_matters: If a connected account was rejected by your platform and needs re-enabling after merchant remediation or a false positive, reverse the rejection. - before: Reversing a rejection required contacting Stripe support. - sources: , - gotchas: "ACCOUNT_ID (required): Path parameter identifying the account to unreject."; "YOUR_SECRET_KEY (required): Stripe secret key used for request authentication."; "Stripe-Version (required): Request header specifying API version; the release note documents 2026-07-29.dahlia."; "Prerequisite: The account must currently be rejected by your platform; Stripe-rejected accounts and accounts that are not currently rejected return an error."; "Prerequisite: Separate pauses on charges or payouts remain after unrejection; only restrictions caused by the rejection are removed."; "Only rejections initiated by your platform can be reversed; Stripe-initiated rejections cannot be reversed through this endpoint." ### Stripe Financial Connections deactivation webhook events (2026-07-29) - slug: stripe-financial-connections-deactivation-webhook-events-5b14ced3b19e - score: 0.91 How to use it: If the integration needs advance warning of Financial Connections deactivation, subscribe the webhook endpoint to the four deactivation events. Handle each event’s `data.object` and prepare for deactivation, such as by prompting users to relink when appropriate. Examples: ``` curl https://api.stripe.com/v1/webhook_endpoints \ -u ":" \ -d "enabled_events[]=financial_connections.account.expected_deactivation_date_updated" \ -d "enabled_events[]=financial_connections.account.upcoming_deactivation" \ -d "enabled_events[]=financial_connections.authorization.expected_deactivation_date_updated" \ -d "enabled_events[]=financial_connections.authorization.upcoming_deactivation" \ --data-urlencode "url=https:///" ``` - why_it_matters: When maintaining an integration that needs to respond to Financial Connections account or authorization deactivation, subscribe to the new webhook events and handle their payloads. - sources: , , - gotchas: "url (required): HTTPS URL for the webhook endpoint."; "enabled_events (required): Event types enabled for this endpoint; specify each event as an array entry. The four deactivation event types were added for webhook endpoint creation and updates."; "financial_connections.account.expected_deactivation_date_updated: Event sent when an Account’s expected deactivation date is set or updated; payload contains the updated Account object."; "financial_connections.account.upcoming_deactivation: Event sent 30 days before an Account is expected to become inactive; payload contains the Account object."; "financial_connections.authorization.expected_deactivation_date_updated: Event sent when an Authorization’s expected deactivation date is set or updated; payload contains the updated Authorization object."; "financial_connections.authorization.upcoming_deactivation: Event sent 30 days before an Authorization is expected to become inactive; payload contains the Authorization object."; "Prerequisite: Provide a publicly accessible HTTPS URL for the registered webhook endpoint."; "Prerequisite: Authenticate the API request with a Stripe secret key."; "Upcoming deactivation events are sent 30 days before an Account or Authorization is expected to become `inactive`."; "Expected deactivation date updated events are sent when the expected deactivation date is set or updated."; "Event payloads contain the relevant updated Account or Authorization object." ### Stripe Financial Connections sessions add explicit configuration options (2026-07-29) - slug: stripe-financial-connections-sessions-add-explicit-configuration-options-c6427339e4c7 - score: 0.94 How to use it: When a session must tailor collected accounts or the authentication fallback, create it with `filters.require_payment_method_support`, `limits.accounts`, and `manual_entry.mode` as needed. After manual entry, use the returned `bank_account_token`; subscribe to the eligibility update event when you need notice of confirmed payment eligibility. Examples: ``` curl https://api.stripe.com/v1/financial_connections/sessions \ -u ":" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d "account_holder[type]"=customer \ -d "account_holder[customer]"= \ -d "permissions[]"=payment_method \ -d "filters[require_payment_method_support]"=at_least_one \ -d "limits[accounts]"= \ -d "manual_entry[mode]"=automatic ``` ``` curl https://api.stripe.com/v1/webhook_endpoints \ -u ":" \ -d "url"= \ -d "enabled_events[]"=financial_connections.account.supported_payment_method_types_updated ``` - why_it_matters: Configure a Financial Connections session to collect accounts and handle authentication according to the integration’s use case. - before: Session behavior was implicitly determined by account holder type. - sources: , - gotchas: "Version: 2026-07-29.dahlia"; "filters.require_payment_method_support: Restricts account selection: `all` makes every linked account payment-eligible; `at_least_one` makes at least one payment-eligible while allowing others; `none` imposes no restriction."; "limits.accounts: Maximum number of accounts a user can link in a session."; "manual_entry.mode: Controls manual bank entry fallback: `automatic` lets Stripe manage it; `disabled` removes the option. These values are alternatives."; "bank_account_token: Returned on the Session object when the user completes manual entry."; "enabled_events[] (required): Webhook event types to enable; include `financial_connections.account.supported_payment_method_types_updated` for payment eligibility notifications."; "Prerequisite: For the new options, use API version `2026-07-29.dahlia`; Stripe says to upgrade SDKs to the corresponding version if used, or send the `Stripe-Version` header for direct API requests. Upgrade the webhook endpoint API version as well."; "`filters.require_payment_method_support` accepts `all`, `at_least_one`, or `none`."; "`manual_entry.mode` accepts `automatic` or `disabled`."; "`bank_account_token` is returned when a user completes manual entry." ### Stripe FPX adds BNP Paribas, Citibank, and MBSB Bank values (2026-07-29) - slug: stripe-fpx-adds-bnp-paribas-citibank-and-mbsb-bank-values-45e8a4337a3e - score: 0.92 How to use it: For BNP Paribas or Citibank B2B payments, create an FPX PaymentMethod with the corresponding `bank` value; for MBSB Bank B2B or B2C payments, use `mbsb_bank`. Examples: ``` curl https://api.stripe.com/v1/payment_methods \ -u "" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d type=fpx \ -d fpx[bank]= ``` - why_it_matters: Update an FPX integration to accept payments from BNP Paribas or Citibank business customers, or from MBSB Bank business and consumer customers. - before: The integration could not pass these newly added bank values to accept FPX payments from these customers. - sources: , , , - gotchas: "type (required): PaymentMethod type; use `fpx` for FPX."; "fpx[bank]: For BNP Paribas or Citibank B2B, pass `bnp_paribas` or `citibank`; for MBSB Bank B2B or B2C, pass `mbsb_bank`. The release note does not state whether this parameter is required."; "Prerequisite: FPX is available to Stripe accounts in Malaysia; the business must provide its Business Registration Number to process FPX charges and receive payouts."; "BNP Paribas and Citibank are supported for B2B transactions."; "MBSB Bank is supported for both B2B and B2C transactions." ### Stripe hosted invoice page supports MB WAY (2026-07-29) - slug: stripe-hosted-invoice-page-supports-mb-way-d1beef856979 - score: 0.97 How to use it: For EUR invoices or subscriptions paid through Stripe’s hosted invoice page, set `collection_method` to `send_invoice` and enable MB WAY in the Dashboard or via `payment_settings.payment_method_types`. Customers authorize each payment on the hosted invoice page. Examples: ``` curl https://api.stripe.com/v1/invoices -u "" -H "Stripe-Version: 2026-07-29.dahlia" -d customer= -d collection_method=send_invoice -d "payment_settings[payment_method_types][]=mb_way" ``` ``` curl https://api.stripe.com/v1/subscriptions -u "" -H "Stripe-Version: 2026-07-29.dahlia" -d customer= -d "items[0][price]=" -d collection_method=send_invoice -d "payment_settings[payment_method_types][]=mb_way" ``` - why_it_matters: When configuring invoices or subscriptions for customers paying in EUR through the hosted invoice page, enable MB WAY with invoice-based collection. - sources: , , , - gotchas: "collection_method (required): Set to `send_invoice`; MB WAY invoices and subscriptions require this collection method. The API parameter is optional generally."; "payment_settings.payment_method_types (required): Array of payment method types to provide to the invoice’s PaymentIntent; set to `mb_way`. The API parameter is optional generally."; "payment_settings: Subscription payment settings passed to invoices created by the subscription."; "customer (required): Customer identifier; required to create a subscription."; "items (required): Subscription items with attached prices; up to 20."; "payment_settings.payment_method_types[]: Invoice API documents this as an optional list of payment method types for the invoice’s PaymentIntent. `mb_way` was not found in the opened API reference."; "Prerequisite: MB WAY supports EUR presentment; Stripe accounts in supported business locations can accept it. Invoices and subscriptions support MB WAY only with `send_invoice`."; "Prerequisite: Subscription creation requires a customer and at least one item with an attached price."; "MB WAY supports EUR payments."; "MB WAY requires customer authorization for each payment and is only available with the `send_invoice` collection method; customers complete payment through the hosted invoice page." ### Stripe invoices and subscriptions accept Alipay with send_invoice collection (2026-07-29) - slug: stripe-invoices-and-subscriptions-accept-alipay-with-send-invoice-collection-9554cc9ec1e9 - score: 0.92 How to use it: When an invoice or subscription uses `collection_method=send_invoice`, set `payment_settings.payment_method_types` to include `alipay`. For an existing object, update that setting on the Invoice or Subscription. Examples: ``` curl https://api.stripe.com/v1/subscriptions \ -u ":" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d customer= \ -d collection_method=send_invoice \ -d days_until_due= \ -d "items[0][price]=" \ -d "payment_settings[payment_method_types][0]=alipay" ``` ``` curl -X POST https://api.stripe.com/v1/invoices/ \ -u ":" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d "payment_settings[payment_method_types][0]=alipay" ``` ``` curl -X POST https://api.stripe.com/v1/subscriptions/ \ -u ":" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d "payment_settings[payment_method_types][0]=alipay" ``` - why_it_matters: Configure an invoice or subscription to accept Alipay when collecting payment by sending an invoice. - sources: , , - gotchas: "collection_method: Use `send_invoice` for Alipay; for subscriptions, `days_until_due` is also valid only with this collection method."; "payment_settings.payment_method_types: List of payment method types to provide to the invoice’s PaymentIntent. Include `alipay`."; "payment_settings.payment_method_types[]: Array entry containing the payment method type; set an entry to `alipay`. Sub-key details and whether this conflicts with other payment settings were not found in the accessible current-version docs."; "Prerequisite: Creating a subscription requires an existing customer and price; the documented create request also requires subscription items. `days_until_due` applies when collection method is `send_invoice`."; "Prerequisite: Stripe’s Alipay guide says to enable Alipay in the Dashboard. Business eligibility restrictions apply; recurring payments require approval."; "For both Invoice and Subscription objects, `alipay` is only supported when `collection_method` is `send_invoice`." ### Stripe Payment Intents and Setup Intents add allowed_payment_method_types (2026-07-29) - slug: stripe-payment-intents-and-setup-intents-add-allowed-payment-method-types-22ca61ab1793 - score: 0.97 How to use it: When an integration manually specifies accepted payment methods and wants Stripe to filter incompatible types, use `allowed_payment_method_types` on PaymentIntent and SetupIntent create, update, or confirm calls. Pass the existing type array, remove incompatible-method error handling, and read the response `payment_method_types` for the compatible subset. Examples: ``` curl https://api.stripe.com/v1/setup_intents \ -u "" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d "allowed_payment_method_types[]=card" ``` ``` curl https://api.stripe.com/v1/payment_intents/ \ -u "" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d "allowed_payment_method_types[]=card" ``` - why_it_matters: When updating an integration to accept a set of payment methods while allowing Stripe to filter incompatible types, migrate the relevant intent calls to the new parameter. - before: Use `payment_method_types` to specify accepted methods; incompatible methods return an error. - sources: , , , - gotchas: "allowed_payment_method_types: Array of allowed payment method type enums; Stripe uses only types in the list when determining the types to offer. Mutually exclusive with `payment_method_types`, `excluded_payment_method_types`, `automatic_payment_methods`, and `payment_method_configuration`."; "payment_method_types: Response property containing the resulting payment method types."; "Prerequisite: Use the Stripe API version `2026-07-29.dahlia` for the documented request shape; authenticate with a secret key."; "`allowed_payment_method_types` accepts an array of payment method types and filters it to methods compatible with parameters such as `currency`, `amount`, and `customer`."; "The response `payment_method_types` property reflects the resulting compatible subset."; "`allowed_payment_method_types` is mutually exclusive with `payment_method_types`, `excluded_payment_method_types`, `automatic_payment_methods`, and `payment_method_configuration`." ### Stripe Payment Link update endpoint accepts setup_future_usage (2026-07-29) - slug: stripe-payment-link-update-endpoint-accepts-setup-future-usage-73c45f1f544d - score: 0.91 How to use it: When updating an existing Payment Link, set `payment_intent_data.setup_future_usage` to `on_session` or `off_session` to indicate the intended reuse of the payment method collected during Checkout. Examples: ``` curl https://api.stripe.com/v1/payment_links/ \ -u ":" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d "payment_intent_data[setup_future_usage]=off_session" ``` - why_it_matters: Set future payment method reuse behavior when updating an existing Payment Link. - before: Requests including `payment_intent_data.setup_future_usage` returned a 400 error before this change. - sources: , - gotchas: "payment_intent_data: Subset of parameters passed to PaymentIntent creation for Checkout Sessions in `payment` mode."; "payment_intent_data.setup_future_usage: Set to `on_session` or `off_session` to indicate intended reuse of the payment method collected during Checkout. The future usage docs recommend `off_session` when payments may occur both on and off session."; "Prerequisite: A Payment Link ID and Stripe secret key are needed for the documented update request. This API parameter applies to Checkout Sessions in `payment` mode."; "The value indicates how the payment method collected during the Checkout Session is intended to be reused." ### Stripe Payment Link update endpoint adds shipping, consent, and future-usage parameters (2026-07-29) - slug: stripe-payment-link-update-endpoint-adds-shipping-consent-and-future-usage-param-53f27274d051 - score: 0.97 How to use it: When updating an existing Payment Link, send the needed `shipping_options`, `consent_collection`, or `payment_intent_data.setup_future_usage` fields. Use the documented values for future usage; the update API requires the Payment Link ID and secret-key authentication. Examples: ``` curl https://api.stripe.com/v1/payment_links/ \ -u "" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d "shipping_options[0][shipping_rate]=" ``` ``` curl https://api.stripe.com/v1/payment_links/ \ -u "" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d "payment_intent_data[setup_future_usage]=off_session" ``` ``` curl https://api.stripe.com/v1/payment_links/ \ -u "" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d "consent_collection[promotions]=auto" ``` - why_it_matters: Update an existing Payment Link's shipping options, consent settings, or payment method reuse behavior through the API. - before: These parameters were previously configurable only through the Dashboard; requests including `payment_intent_data.setup_future_usage` returned HTTP 400. - sources: , - gotchas: " (required): ID of the Payment Link to update."; " (required): Stripe secret API key used for HTTP basic authentication."; "shipping_options: Shipping rate options applied to checkout sessions created by the Payment Link; release note specifies up to five objects and empty array removes all options."; "shipping_options[].shipping_rate (required): Existing Shipping Rate ID for the shipping option, per the release note."; "consent_collection: Optional object to configure active customer consent collection."; "consent_collection.payment_method_reuse_agreement.position: Controls where the payment method reuse agreement is displayed; allowed values not found."; "consent_collection.promotions: Controls whether to display a promotional communications consent checkbox; allowed values not found."; "consent_collection.terms_of_service: Controls whether to display a terms of service acceptance checkbox; allowed values not found."; "payment_intent_data.setup_future_usage: Indicates whether payment methods collected during checkout are intended for reuse; release note allows `on_session` or `off_session`."; "Prerequisite: Authenticate the request with a Stripe secret key and provide the Payment Link ID."; "Prerequisite: A Payment Link must already exist. Stripe's page prerequisite example creates a Price and then a Payment Link."; "Prerequisite: Each shipping rate must already exist, per the release note."; "Each shipping_options array can contain up to five shipping rate objects, each referencing an existing Shipping Rate ID."; "payment_intent_data.setup_future_usage accepts `on_session` or `off_session`."; "The consent settings described are payment method reuse agreement position, promotions consent checkbox, and terms of service checkbox." ### Stripe SharedPaymentToken adds redirect_to_url next actions (2026-07-29) - slug: stripe-sharedpaymenttoken-adds-redirect-to-url-next-actions-93c027e2686d - score: 0.96 How to use it: When an integration handles Shared Payment Token or requested Delegated Checkout Session next actions, set `use_stripe_sdk` according to whether a Stripe client-side SDK handles them. When handling outside a client-side SDK, provide `return_url` and accept either `use_stripe_sdk` or `redirect_to_url` as `next_action.type`. Examples: ``` curl https://api.stripe.com/v1/shared_payment/issued_tokens -u "" -H "Stripe-Version: 2026-07-29.preview" -d payment_method= -d "seller_details[network_business_profile]=" -d "usage_limits[currency]=usd" -d "usage_limits[expires_at]=" -d "usage_limits[max_amount]=" -d use_stripe_sdk=true ``` ``` curl https://api.stripe.com/v1/shared_payment/issued_tokens -u "" -H "Stripe-Version: 2026-07-29.preview" -d payment_method= -d "seller_details[network_business_profile]=" -d "usage_limits[currency]=usd" -d "usage_limits[expires_at]=" -d "usage_limits[max_amount]=" -d use_stripe_sdk=false -d return_url= ``` - why_it_matters: Update an integration that creates Shared Payment Tokens or confirms requested Delegated Checkout Sessions to handle 3DS next actions. - before: `next_action.type` on SharedPaymentToken returned only `use_stripe_sdk`; integrations using client-side SDKs did not set `use_stripe_sdk` when creating a Shared Payment Token or confirming a requested Delegated Checkout Session. - sources: , , - gotchas: "use_stripe_sdk: Optional boolean on SharedPaymentIssuedToken creation. Set true when Stripe.js, iOS, or Android client-side SDKs handle next actions. Release note says false requires `return_url`."; "return_url (required): Required by the release note when `use_stripe_sdk` is false; parameter definition not independently verified in the accessible API page."; "next_action.type: Release note says it can be `use_stripe_sdk` or `redirect_to_url`; handle both values."; "Prerequisite: Create a PaymentMethod first; the create page example uses a US bank account PaymentMethod."; "Prerequisite: The create request example requires `payment_method`, `seller_details`, and `usage_limits`."; "When `use_stripe_sdk` is `false`, a `return_url` is required."; "`redirect_to_url` is returned for 3DS authentication flows when `use_stripe_sdk` is `false`."; "`next_action.type` can now be either `use_stripe_sdk` or `redirect_to_url`; integrations that only handle `use_stripe_sdk` may need to update their logic." ### Stripe Top-ups accept US bank account PaymentMethods (2026-07-29) - slug: stripe-top-ups-accept-us-bank-account-paymentmethods-27298d0a2e9e - score: 0.96 How to use it: For US top-ups using the API version that adds PaymentMethod support, create the top-up with a `us_bank_account` PaymentMethod ID in `payment_method`. Optionally set `payment_method_options.us_bank_account.network`; it defaults to `ach`. Examples: ``` curl https://api.stripe.com/v1/topups \ -u "" \ -H "Stripe-Version: 2026-07-29.dahlia" \ -d amount= \ -d currency= \ -d payment_method= \ -d "payment_method_options[us_bank_account][network]=" ``` - why_it_matters: Create and manage US top-ups using the Payment Methods API. - before: Use the Sources API when creating and managing US top-ups. - sources: , - gotchas: "amount (required): Positive integer amount to transfer."; "currency (required): Lowercase supported three-letter ISO currency code."; "payment_method: ID of the PaymentMethod to use; for this change, its type must be `us_bank_account`."; "payment_method_options: Object containing top-up payment-method-specific configuration."; "payment_method_options.us_bank_account.network: US bank transfer network; defaults to `ach`. The docs retrieved do not enumerate allowed values for this top-up parameter."; "Prerequisite: Use API version `2026-07-29.dahlia` or later for this behavior. For REST requests, Stripe's upgrade instructions say to send the version in the `Stripe-Version` header."; "Applies to top-ups in the US."; "Currently supports only `us_bank_account` payment method types." ### Stripe Checkout Sessions accept billing_cycle_anchor_config (2026-06-24) - slug: stripe-checkout-sessions-accept-billing-cycle-anchor-config-b1f560f9ed6d - score: 0.95 How to use it: When creating a Checkout Session for a recurring subscription, set `mode=subscription` and `subscription_data[billing_cycle_anchor_config][day_of_month]` to the desired billing day. The `day_of_month` field is required; `hour`, `minute`, `month`, and `second` are optional, and this configuration cannot be combined with `billing_cycle_anchor` or trial period parameters. Examples: ``` curl https://api.stripe.com/v1/checkout/sessions -u "" -H "Stripe-Version: 2026-06-24.dahlia" --data-urlencode "success_url=https://example.com/success" -d "line_items[0][price]=" -d "line_items[0][quantity]=1" -d "mode=subscription" -d "subscription_data[billing_cycle_anchor_config][day_of_month]=" ``` - why_it_matters: When implementing subscription-mode Checkout Session creation that aligns subscribers to a fixed billing date, configure the session's billing cycle anchor. - sources: , - gotchas: "mode (required): Set to `subscription` to use Stripe Billing for fixed-price subscriptions."; "line_items (required): Required for subscription mode; pass recurring Price items."; "subscription_data[billing_cycle_anchor_config][day_of_month] (required): Required day of month for the configured billing cycle anchor."; "subscription_data[billing_cycle_anchor_config][hour]: Optional hour for the configured billing cycle anchor."; "subscription_data[billing_cycle_anchor_config][minute]: Optional minute for the configured billing cycle anchor."; "subscription_data[billing_cycle_anchor_config][month]: Optional month for the configured billing cycle anchor."; "subscription_data[billing_cycle_anchor_config][second]: Optional second for the configured billing cycle anchor."; "subscription_data[billing_cycle_anchor_config]: Configuration is mutually exclusive with `subscription_data[billing_cycle_anchor]` and any trial period parameters."; "Prerequisite: Create a recurring Price and use its ID in `line_items`; the API reference shows creating a monthly USD Price before creating the Checkout Session."; "Prerequisite: Authenticate the API request with a Stripe secret key."; "Available for Checkout Sessions in subscription mode."; "`day_of_month` is required; `hour`, `minute`, `month`, and `second` are optional."; "`billing_cycle_anchor_config` is mutually exclusive with `billing_cycle_anchor` and any trial period parameters." ### Stripe invoice preview supports subscription pauses (2026-06-24) - slug: stripe-invoice-preview-supports-subscription-pauses-06f65aeb5a26 - score: 0.97 How to use it: When previewing a subscription pause, create a preview invoice with `subscription_details.pause`, `invoicing_behavior=invoice`, and `bill_for` settings that produce billable unused time or metered usage. Use the returned preview invoice and expanded projected subscription state; the preview does not modify the subscription. Examples: ``` curl https://api.stripe.com/v1/invoices/create_preview \ -u "<>:" \ -d subscription= \ -d "subscription_details[pause][invoicing_behavior]=invoice" \ -d "subscription_details[pause][bill_for][unused_time_from][type]=now" \ -d "subscription_details[pause][bill_for][outstanding_usage_through][type]=now" \ -d "expand[]=parent.subscription_details.subscription" ``` - why_it_matters: When implementing subscription pausing, preview the billing impact and projected subscription state before changing the subscription. - sources: , , , , - gotchas: "Availability: Preview API version 2026-06-24.preview"; "subscription (required): Subscription identifier for the upcoming invoice preview."; "subscription_details.pause.invoicing_behavior (required): Set to `invoice` to receive a preview invoice; `pending_invoice_item` returns 404."; "subscription_details.pause.bill_for.unused_time_from.type (required): `now` credits unused licensed time from pause time; `item_current_period_start` credits from each item's period start; `none` does not credit unused time."; "subscription_details.pause.bill_for.outstanding_usage_through.type (required): `now` bills metered usage from current period start through pause time; `none` does not bill current-period metered usage."; "expand[]: Set to `parent.subscription_details.subscription` to see the projected subscription state after pausing; these changes do not persist."; "Prerequisite: For a restricted API key, grant `invoice_read` to preview invoices."; "Prerequisite: A valid subscription/customer must be provided; preview invoice creation requires valid customer information."; "`invoicing_behavior` must be `invoice` to receive a preview invoice; `pending_invoice_item` returns a 404 error."; "`bill_for` must produce billable amounts for unused licensed time or outstanding metered usage; if pausing would not create debits or credits, the endpoint returns a 404 error." ### Stripe Subscriptions API supports invoice description, footer, and custom_fields (2026-06-24) - slug: stripe-subscriptions-api-supports-invoice-description-footer-and-custom-fields-2d0601f4f03d - score: 0.99 How to use it: When setting details on subscription-generated invoices, set `invoice_settings.description`, `invoice_settings.footer`, and `invoice_settings.custom_fields` when creating or updating a Subscription; retrieve the Subscription to read them. Examples: ``` curl https://api.stripe.com/v1/subscriptions \ -u "" \ -H "Stripe-Version: 2026-06-24.dahlia" \ -d "customer=" \ -d "items[0][price]=" \ -d "invoice_settings[description]=" \ -d "invoice_settings[footer]=