Migrate to Confirmation Tokens

Finalise payments on the server by using a ConfirmationToken instead of a PaymentMethod.

Use this guide to learn how to finalise payments on the server by using a ConfirmationToken instead of a PaymentMethod to send data collected from your client to your server.

A ConfirmationToken holds a superset of the data found on a PaymentMethod, such as shipping information, and enables new features as we build them.

Create the Confirmation Token client-side

Instead of calling stripe.createPaymentMethod, call stripe.createConfirmationToken to create a ConfirmationToken object. Pass this ConfirmationToken to the server to confirm the PaymentIntent.

The stripe.createConfirmationToken method accepts the same parameters as stripe.createPaymentMethod (through params.payment_method_data), plus additional shipping and return_url parameters.

Before

After

checkout.js

// Create the PaymentMethod using the details collected by the Payment Element.
const {error, paymentMethod} = await stripe.createPaymentMethod({
 elements,
 params: {
 billing_details: {
 name: 'Jenny Rosen',
 }
 }
});


if (error) {
 // This point is only reached if there's an immediate error when creating the PaymentMethod.
 // Show the error to your customer (for example, payment details incomplete)
 handleError(error);
 return;
}

// Create and confirm the PaymentIntent
const res = await fetch("/create-confirm-intent", {
 method: "POST",
 headers: {"Content-Type": "application/json"},
 body: JSON.stringify({
 paymentMethodId: paymentMethod.id,
 }),
});

checkout.js

Create and submit the payment to Stripe server-side

You pass the ConfirmationToken to the server to confirm the PaymentIntent, rather than passing a PaymentMethod as you did before. The properties stored on the ConfirmationToken are applied to the Intent when its ID is provided to the confirmation_token parameter at confirmation time.

Note

If you already provide shipping and return_url on the ConfirmationToken, you don’t need to provide those fields again when confirming the PaymentIntent.

Before

After

server.js

server.js

app.post('/create-confirm-intent', async (req, res) => {
 try {
 const intent = await stripe.paymentIntents.create({
 confirm: true,
 amount: 1099,
 currency: 'usd',
 // In the latest version of the API, specifying the `automatic_payment_methods` parameter is optional because Stripe enables its functionality by default.
 automatic_payment_methods: {enabled: true},
 use_stripe_sdk: true,
 // the ConfirmationToken ID sent by your client that already has the shipping, mandate_data, and return_url data
 confirmation_token: req.body.confirmationTokenId,
 });
 res.json({
 client_secret: intent.client_secret,
 status: intent.status
 });
 } catch (err) {
 res.json({
 error: err
 })
 }
});

Any parameters provided directly to the PaymentIntent or SetupIntent at confirmation time, such as shipping override corresponding properties on the ConfirmationToken.

Optional Setting conditional parameters setup_future_usage or capture_method based on payment method

See also

• Design an integration