Learn how to migrate your existing cards and Charges API integration.
Migrating your payment flow can be daunting. It is safe to incrementally adopt the Payment Intents API and use it in parallel with the Charges API. To this end, you can split up the migration into the following steps:
- Update your API version and your client library.
- If applicable, migrate code that reads from Charge properties so that you have a consistent read path between charges created by the Charges API and charges created by the Payment Intents API. This ensures a read-side integration that works for both your old and new payments integrations.
- Migrate your existing Charges API integration on Web, iOS, and Android to use the Payment Intents API.
- Migrate your integration that saves cards on Customer objects.
- Test with regulatory test cards to ensure your upgraded integration handles authentication correctly.
Update your API version and your client library
While the Payment Intents API works on all API versions, we recommend that you upgrade to the latest API version. If you decide to use an API version older than 2019-02-11, note the following two changes as you go through the code examples:
requires_sourcehas been renamed to
requires_source_actionhas been renamed to
In addition, if you use one of our Client libraries, upgrade to the latest version of the library in order to use the Payment Intents API.
Migrate your one-time payment flows
Migrate your integration that saves cards on Customer objects
Access saved payment methods
To display the customer’s previously saved Cards, Sources, and PaymentMethods, list the payment methods instead of reading the sources property of the customer object. This is required because new PaymentMethods added to a customer will not be duplicated in the sources property of the customer object.
Test the integration
It’s important to thoroughly test your integration to make sure you’re correctly handling cards that require additional authentication and cards that don’t. Use these card numbers in test mode with any expiration date in the future and any three digit CVC code to validate your integration when authentication is required and when it’s not required.
|Required on setup or first transaction||This test card requires authentication for one-time payments. However, if you set up this card using the Setup Intents API and use the saved card for subsequent payments, no further authentication is needed.|
|Required||This test card requires authentication on all transactions.|
|Required||This test card requires authentication, but payments will be declined with an |
|Supported||This test card supports authentication via 3D Secure 2, but does not require it. Payments using this card do not require additional authentication in test mode unless your test mode Radar rules request authentication.|
Use these cards in your application or the payments demo to see the different behavior.