Quick Summary
This diff covers 100 breaking changes across 8 account-related endpoints in the Stripe API, spanning /v1/account, /v1/account_links, /v1/account_sessions, /v1/accounts, /v1/accounts/{account}, /v1/accounts/{account}/bank_accounts, /v1/accounts/{account}/bank_accounts/{id}, and /v1/accounts/{account}/capabilities. The changes introduce new enum values in three distinct areas: 3D Secure version strings (2.3.0, 2.3.1), iDEAL payment method identifiers (adyen bank, ADYBNL2A BIC), and a new Polish tax ID type (pl_nip) propagated through AccountSettings invoice tax ID fields. Because every change is classified as breaking, any schema validation, exhaustive enum matching, or strict deserialization logic in your integration is at risk of failing if it does not account for these additions.
---
Changes by Severity
#### 🔴 Immediate Action Required
three_d_secure version field within PaymentFlowsSetupIntentSetupAttempt/payment_method_details/card/three_d_secure now includes 2.3.0 and 2.3.1 as valid values. This affects all 8 endpoints. Any switch/match statement or allowlist that enumerates 3DS versions will reject or mishandle these values.bank and bic enum expansion — payment_method_details/ideal/bank gains the value adyen; payment_method_details/ideal/bic gains ADYBNL2A. Both appear under PaymentFlowsSetupIntentSetupAttempt in error response bodies across /v1/account, /v1/account_links, /v1/account_sessions, and /v1/accounts. Integrations that map iDEAL bank codes to display names or routing logic need to handle these new entries.pl_nip tax ID type — The type field on tax_id objects nested under AccountSettings/invoices/default_account_tax_ids/items now includes pl_nip as a valid enum value. This propagates through multiple response paths including settings/anyOf[subschema #1: AccountSettings] on /v1/account, and through on_behalf_of and error/source chains on connected account endpoints. Tax ID rendering, validation, and storage logic that uses an enum allowlist is directly affected.---
Migration Playbook
1. Audit enum handling for three_d_secure version fields.
Locate all code that reads or switches on three_d_secure.version (or equivalent deserialized field) in SetupIntent attempt responses. Add 2.3.0 and 2.3.1 to any allowlist, match arm, or mapping table.
```typescript
// Before
type ThreeDSecureVersion = '1.0.2' | '2.1.0' | '2.2.0';
// After
type ThreeDSecureVersion = '1.0.2' | '2.1.0' | '2.2.0' | '2.3.0' | '2.3.1';
```
2. Update iDEAL bank and BIC mappings.
Search for any lookup tables, display-name maps, or routing logic keyed on payment_method_details.ideal.bank or payment_method_details.ideal.bic. Add entries for adyen and ADYBNL2A.
```python
IDEAL_BANK_NAMES = {
# existing entries ...
"adyen": "Adyen",
}
IDEAL_BIC_CODES = {
# existing entries ...
"ADYBNL2A": "Adyen",
}
```
3. Extend tax_id.type handling to include pl_nip.
Any code that validates, formats, or stores tax ID types from AccountSettings.invoices.default_account_tax_ids needs to accept pl_nip. This includes database enum columns, GraphQL enums, and frontend display logic.
```sql
-- Example: extend a Postgres enum
ALTER TYPE tax_id_type ADD VALUE IF NOT EXISTS 'pl_nip';
```
4. Check error response deserialization paths.
The new enum values appear inside nested error response schemas (e.g., error/setup_intent/latest_attempt/... and error/source/...). If your error handling deserializes these nested objects into typed structs, update those struct definitions to include the new values before deploying.
```go
// Go example
type TaxIDType string
const (
// existing constants ...
TaxIDTypePLNIP TaxIDType = "pl_nip"
)
```
5. Validate changes against all 8 affected endpoints.
The enum additions are not isolated to a single endpoint — they appear consistently across /v1/account, /v1/account_links, /v1/account_sessions, /v1/accounts, /v1/accounts/{account}, /v1/accounts/{account}/bank_accounts, /v1/accounts/{account}/bank_accounts/{id}, and /v1/accounts/{account}/capabilities. Run integration tests against each endpoint to confirm deserialization succeeds with the new values.
6. Regenerate SDK or OpenAPI client code.
If your team uses a generated client from the Stripe OpenAPI spec, pull the updated spec at commit 7d73d5593bf0 and regenerate. Verify the generated types include all new enum members before replacing the existing client.
```bash
# Example using openapi-generator
openapi-generator generate \
-i https://raw.githubusercontent.com/stripe/openapi/7d73d5593bf01123d9655114c375972a591eb9b0/openapi/spec3.json \
-g typescript-axios \
-o ./generated/stripe-client
```
7. Review on_behalf_of connected account flows.
The pl_nip enum addition propagates through on_behalf_of/anyOf[subschema #2: Account]/settings/anyOf[subschema #1: AccountSettings] paths. If your platform uses on_behalf_of for connected accounts in Poland, verify that tax ID handling in those flows is updated consistently with step 3.
---
Verification Checklist
three_d_secure.version enum references updated to include 2.3.0 and 2.3.1bank field handling includes adyen in all lookup tables and display mappingsbic field handling includes ADYBNL2A in all BIC-to-institution mappingstax_id.type allowlists, database enums, and frontend components accept pl_nipsetup_intent and source paths handles all new enum values without throwing/v1/account, /v1/account_links, /v1/account_sessions, /v1/accounts, and the three /v1/accounts/{account} sub-endpoints7d73d5593bf0 and deployedon_behalf_of) flows for Polish accounts tested with pl_nip tax ID type---