Updates card property requirements and adds 3D Secure authentication properties to Payment Records
What’s new
Updates the Payment Record object to provide more payments orchestration flexibility by making several card properties optional and adding 3D Secure authentication properties to capture enhanced transaction security data.
Makes the following properties of the payment_method_details.card hash optional instead of required:
- last4 : The last 4 digits of the card number
- brand : The card brand (Visa, Mastercard, and so on)
- exp_month : The card’s expiration month
- exp_year : The card’s expiration year
- moto : Indicates a the related setting (mail order or telephone order) payment
- funding : The card funding type (such as credit or debit)
Adds the following optional properties to the payment_method_details.card.three_d_secure hash:
- electronic_commerce_indicator : The Electronic Commerce Indicator (ECI), a protocol-level field indicating what degree of authentication was performed
- exemption_indicator : The exemption requested via 3DS and accepted by the issuer at authentication time
- exemption_indicator_applied : Whether Stripe requested the value of exemption _ indicator in the transaction
Impact
Several card properties on the Payment Record object are now optional instead of required. Because these objects can be rendered at various points in the payment lifecycle, not all card fields are guaranteed to be available. This change makes the API more flexible for payments orchestration scenarios, particularly when working with external processors or recording payment attempts without complete card data.
The new three_d_secure properties provide useful 3D Secure authentication information that was previously unavailable on the Payment Record. This brings the Payment Record closer to parity with the Charge resource.
Changes
| Parameters | Change | Resources or endpoints |
|---|---|---|
| electronic_commerce_indicator exemption_indicator exemption_indicator_applied | Added | PaymentAttemptRecord. payment_method_details. card. three_d_secure PaymentRecord. payment_method_details. card. three_d_secure |
| Fields | Change | From → to |
| PaymentAttemptRecord. payment_method_details. card. brand PaymentRecord. payment_method_details. card. brand | Changed | enum → nullable(enum) |
| PaymentAttemptRecord. payment_method_details. card. exp_month PaymentRecord. payment_method_details. card. exp_month | Changed | longInteger → nullable(longInteger) |
| PaymentAttemptRecord. payment_method_details. card. exp_year PaymentRecord. payment_method_details. card. exp_year | Changed | longInteger → nullable(longInteger) |
| PaymentAttemptRecord. payment_method_details. card. funding PaymentRecord. payment_method_details. card. funding | Changed | enum('credit'|'debit'|'prepaid'|'unknown') → nullable(enum('credit'|'debit'|'prepaid'|'unknown')) |
| PaymentAttemptRecord. payment_method_details. card. last4 PaymentRecord. payment_method_details. card. last4 | Changed | string → nullable(string) |
| PaymentAttemptRecord. payment_method_details. card. moto PaymentRecord. payment_method_details. card. moto | Changed | boolean → nullable(boolean) |
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2026-03-25. dahlia
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
- In Workbench, perform the upgrade . You can roll back the version for 72 hours.
Learn more about Stripe API upgrades.