Payment Intents add card-not-present surcharge fields

Introduced 2026-03-25 · score 0.95

HOW TO USE IT

For card-not-present PaymentIntents with a surcharge, include the surcharge in the total `amount` and provide `amount_details.surcharge.amount` when creating, updating, confirming, or capturing. Configure `amount_details.surcharge.enforce_validation` as `automatic`, `enabled`, or `disabled`; `automatic` is the default and changeable, while `enabled` and `disabled` cannot be changed.

curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  -d amount=<TOTAL_AMOUNT_IN_SMALLEST_CURRENCY_UNIT> \
  -d currency=<CURRENCY> \
  -d "amount_details[surcharge][amount]=<SURCHARGE_AMOUNT>" \
  -d "amount_details[surcharge][enforce_validation]=automatic"

curl https://api.stripe.com/v1/payment_intents/<PAYMENT_INTENT_ID> \
  -u "<<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  -d amount=<TOTAL_AMOUNT_IN_SMALLEST_CURRENCY_UNIT> \
  -d "amount_details[surcharge][amount]=<SURCHARGE_AMOUNT>" \
  -d "amount_details[surcharge][enforce_validation]=automatic"

curl https://api.stripe.com/v1/payment_intents/<PAYMENT_INTENT_ID>/confirm \
  -u "<<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  -d amount=<TOTAL_AMOUNT_IN_SMALLEST_CURRENCY_UNIT> \
  -d "amount_details[surcharge][amount]=<SURCHARGE_AMOUNT>" \
  -d "amount_details[surcharge][enforce_validation]=automatic"

WHY THIS HELPS

Update a Payment Intents integration to create, update, confirm, or capture card-not-present payments with a surcharge.

BEFORE THIS CHANGE

Calculate the surcharge separately from the Payment Intent total.

REQUIREMENTS AND LIMITATIONS

Version: 2026-03-25.preview
Availability: Preview API version 2026-03-25.preview
amount (required): Total amount, inclusive of the surcharge, in the smallest currency unit.
amount_details.surcharge.amount (required): Identifies the surcharge amount.
amount_details.surcharge.enforce_validation: Validation enforcement setting; `automatic` is the default and changeable, while `enabled` and `disabled` cannot be changed.
amount_details.surcharge.enforce_validation=automatic: Enforces validation; can be changed.
amount_details.surcharge.enforce_validation=enabled: Enforces validation; cannot be changed.
amount_details.surcharge.enforce_validation=disabled: Does not enforce validation; cannot be changed.
Prerequisite: Use Stripe API version `2026-03-25.preview`; requests require a secret key in the documented curl examples.
If `amount_details.surcharge.enforce_validation` is `enabled` or `disabled`, it cannot be changed.
If `amount_details.surcharge.enforce_validation` is `automatic`, validation is enforced but the setting can be changed.
Pass the total amount inclusive of the surcharge when creating, updating, confirming, or capturing a Payment Intent with a surcharge.

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card

Tools change faster than your agent’s training data.

Changes

Payment Intents add card-not-present surcharge fields