Use this migration path if your integration waits for the response from the client before finalizing the payment on the server. Server-side confirmation has the following limitations:
- Only supports cards: You’ll have to write more code to support ACH and popular regional payment methods separately.
- Double-charge risk: When you create a new PaymentIntent each time your customer attempts to pay, you risk accidentally double-charging your customer. Be sure to follow best practices.
- Extra trip to client: If your customer has a card with 3D Secure or is subject to regulations like Strong Customer Authentication, this integration requires an extra trip to the client to authenticate.
If you don’t mind these limitations, feel free to use this migration path. Otherwise, use the standard migration path, which automatically handles any actions required for collecting payment.
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
“One-time payments” are payment flows that collect card details to be charged once and immediately (e.g. e-commerce purchases, one-off donations). For payment flows that save card details to be charged later or on a recurring basis, follow the migration guide on saving cards.
Pick the migration path that matches your current Stripe integration:
Migrate your integration that saves cards on Customer objects
You will need to change your integration to let Stripe know how you intend to use your customers’ saved cards so we can optimize for the right exemptions. SCA may also require that the card is authenticated before being stored.
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.
Now you have all the information you need to begin migrating an existing Stripe integration to the Payment Intents API with manual confirmation. To learn more, continue reading: