Overview

Stripe has updated the Issuing Token API in version 2026-03-25.dahlia to make the network_data.visa.card_reference_id property optional. Previously, this field was required to always have a string value. This change allows the Stripe Issuing service to support Visa tokens that don't have an associated reference ID.

What Changed

The network_data.visa.card_reference_id field on the Issuing Token object now accepts null values in addition to strings. This aligns with the existing behavior of the MasterCard equivalent field, network_data.mastercard.card_reference_id, which already supported nullable values.

Breaking Change Details:

• Field: Issuing.Token.network_data.visa.card_reference_id
• Change Type: Data type modification
• Before: string (non-nullable)
• After: nullable(string)

Developer Action Items

If your integration accesses the network_data.visa.card_reference_id property, you must update your code to handle null values:

1. Review your code that reads the Visa card reference ID from Issuing Token objects
2. Add null checks before using this field to prevent runtime errors
3. Test thoroughly against the new API version before upgrading to production

Upgrade Path

1. View your current API version in Workbench
2. Upgrade your SDK to the latest version supporting API 2026-03-25.dahlia, or add the Stripe-Version: 2026-03-25.dahlia header to API requests if using a direct HTTP client
3. Update webhook endpoint configurations to use the new API version
4. Test your integration in Stripe's testing environment
5. Perform the upgrade in Workbench (with option to rollback within 72 hours)