Migrate from 2024-04-10 to 2024-06-20

What Changed

stripe.financialConnections.linkAccountSessions.create({
  account_holder: { type: 'customer', customer: 'cus_xyz' }
});

stripe.financialConnections.linkAccountSessions.create({
  account_holder: { type: 'customer', customer: 'cus_xyz' },
  permissions: ['balances', 'transactions']
});

Migration Steps

1. 1

   Update Stripe SDK and Dependencies

   code

   Ensure your Stripe client library (e.g., `stripe-node`, `stripe-python`) is updated to the latest compatible version to support API version 2024-06-20 and its new features/fixes. This ensures you have access to the latest methods and types.

   • ↳Check SDK release notes for version-specific breaking changes.
   • ↳Use semantic versioning for dependencies (e.g., `^X.Y.Z`).
   • ↳Update Stripe CLI tools if used for local testing or webhook forwarding.
2. 2

   Implement Financial Connections Permissions

   code

   Modify your code where `stripe.financialConnections.linkAccountSessions.create` is called to include the new `permissions` array. Explicitly define the data access scope (e.g., 'balances', 'transactions') required for connected accounts to avoid API errors.

   • ↳Carefully choose required permissions to avoid over-requesting data, adhering to PCI compliance and privacy best practices.
   • ↳Refer to Stripe's Financial Connections documentation for all available `permissions` values.
   • ↳Test different permission scopes if your application has varied needs for financial data.
3. 3

   Update API Version Configuration

   config

   Explicitly set the API version in your Stripe client initialization or per-request options to `2024-06-20`. This ensures all API calls from your application respect the new version's behavior and data structures.

   • ↳Update environment variables or configuration files for API version.
   • ↳Verify server-side API version is consistent across development, staging, and production environments.
   • ↳Be aware that client-side SDKs might auto-version, but explicit server-side control is crucial.
4. 4

   Review Webhook Handlers

   code

   Although no specific webhook event breaking changes are noted for this version, it's good practice to review your webhook handlers for any potential new fields or structure changes in relevant objects like `PaymentMethod` or `CheckoutSession`. This helps prevent parsing errors.

   • ↳Use Stripe CLI to replay webhook events for local testing with the new API version.
   • ↳Ensure idempotency in webhook handlers to prevent duplicate processing if an event is re-delivered.
   • ↳Log raw webhook payloads for debugging unexpected structures in staging.
5. 5

   Conduct Comprehensive Testing

   test

   Perform thorough testing across all critical Stripe-related flows in a staging environment. This includes payment processing, refunds, subscriptions, customer management, and especially any new Financial Connections flows you implement. Ensure all changes behave as expected.

   • ↳Use Stripe test cards and test mode for all transactions.
   • ↳Verify webhook event processing end-to-end for all relevant events.
   • ↳Test edge cases and error scenarios, such as failed payments or invalid inputs.
6. 6

   Deploy to Production

   deploy

   Once all testing is complete and successful in your staging environment, deploy the updated code to your production environment. It's advisable to perform this deployment during a low-traffic period to minimize potential impact.

   • ↳Implement a phased rollout strategy if your infrastructure supports it.
   • ↳Ensure rollback procedures are well-defined and tested in case of unforeseen issues.
   • ↳Clear any relevant caches after deployment to ensure new code takes effect immediately.
7. 7

   Monitor Post-Deployment

   verify

   Actively monitor your application's error logs, Stripe logs, and relevant business metrics immediately after deployment to quickly identify and address any unforeseen issues. Pay close attention to API error rates and successful transaction volumes.

   • ↳Set up alerts for Stripe API errors (e.g., 5xx responses) in your monitoring system.
   • ↳Monitor webhook delivery and processing logs for any failures or delays.
   • ↳Check for any sudden changes in payment declines or failed transactions.

Testing Checklist

1. 1.

   Successful one-time payments and recurring billing (if applicable)

   Process test payments for various methods (cards, wallets) and verify subscription renewals.

2. 2.

   Refunds and disputes

   Initiate test refunds and simulate dispute creation/resolution.

3. 3.

   Webhook event processing

   Trigger various Stripe events (e.g., `payment_intent.succeeded`, `customer.created`) and verify your handlers process them correctly.

4. 4.

   Financial Connections linking flow

   Complete the entire Link Account Session process, ensuring bank accounts can be linked and permissions are correctly handled.

5. 5.

   Existing customer and subscription management

   Verify that existing customers can be updated and subscriptions continue to bill without issues.

6. 6.

   Error handling and edge cases

   Test scenarios like invalid card details, insufficient funds, and network errors to ensure graceful failure.

Common Mistakes