Migrating to the Payment Intents API

An integration built with Stripe.js & Elements consists of the following steps:

1. Register your intent to collect payment on the server side
2. Collect payment details on the client side
3. Initiate creation of the payment
4. Fulfill the customer’s order on the server side

Step 1: Register intent to collect payment on the server side

Create a PaymentIntent on your server and make it accessible on the client side.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1099 \
  -d "currency"="usd"

Step 2: Collect payment details on the client side

Use the confirmCardPayment function, which collects the payment information and submits it directly to Stripe.

stripe.createToken(
  cardElement
).then(function(token) {
  // Send token to server
});

stripe.confirmCardPayment(
  INTENT_SECRET_FROM_STEP_1,
  {
    payment_method: {card: cardElement}
  }
).then(function(result) {
  if (result.error) {
    // Display error.message in your UI.
  } else {
    // The payment has succeeded
    // Display a success message
  }
});

Step 3: Initiate creation of the payment

In your existing integration, the final step is using tokenized payment information to create a charge on your server. This is no longer necessary, as the confirmCardPayment function—called in the previous step—initiates creation of the charge.

curl https://api.stripe.com/v1/charges \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{FROM_PREVIOUS_STEP}}" \
  -d "amount"=1099 \
  -d "currency"="usd"

Step 4: Fulfill the customer’s order

With automatic confirmation, the charge is created for you asynchronously based on customer action on the client side, so you must monitor webhooks to determine when the payment completes successfully. To perform steps like order fulfilment after a customer’s payment is successful, implement support for webhooks and monitor the payment_intent.succeeded event.

Now that you have migrated, use the test cards in the following section to verify your upgraded integration handles 3D Secure authentication.

A Payment Intents API integration that collects card information in the checkout flow consists of the following steps:

1. Register your intent to collect payment on the server side
2. Collect payment details on the client side
3. Initiate creation of the payment
4. Fulfill the customer’s order on the server side

Step 1: Register intent to collect payment on the server side

Create a PaymentIntent on your server. Set setup_future_usage to off_session if you primarily intend to charge users when they are outside your application, or on_session if you plan to charge them in the application. If you plan to use the card for both on and off session payments use off_session. Providing the setup_future_usage parameter along with a Customer ID will save the resulting PaymentMethod to that Customer after the PaymentIntent has been confirmed and any required actions from the customer are complete. Next, make the PaymentIntent accessible on the client side.

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "setup_future_usage"="off_session" \
  -d "amount"=1099 \
  -d "currency"="usd"

Step 2: Collect payment details on the client side

Use the confirmCardPayment function, which collects the payment information and submits it directly to Stripe.

stripe.createToken(
// or stripe.createSource
  cardElement
).then(function(token) {
  // Send token to server
});

stripe.confirmCardPayment(
  '{{INTENT_SECRET_FROM_STEP_1}}',
  {
    payment_method: {card: cardElement},
  }
).then(function(result) {
  if (result.error) {
    // Display error.message in your UI.
  } else {
    // The payment has succeeded
    // Display a success message
  }
});

Finally, attach the payment method (paymentIntent.payment_method) to the customer.

curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}}/sources \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{TOKEN_OR_SOURCE}}"

curl https://api.stripe.com/v1/payment_method/{{PAYMENT_METHOD_ID}}/attach \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}"

Step 3: Initiate creation of the payment

In your existing integration, the final step is using tokenized payment information to create a charge on your server. This is no longer necessary, as the confirmCardPayment function—called in the previous step—initiates creation of the charge.

curl https://api.stripe.com/v1/charges \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{FROM_PREVIOUS_STEP}}" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="usd"

Step 4: Fulfill the customer’s order

With automatic confirmation, the charge is created for you asynchronously based on customer action on the client side, so you must monitor webhooks to determine when the payment completes successfully. To perform steps like order fulfilment after a customer’s payment is successful, implement support for webhooks and monitor the payment_intent.succeeded event.

Now that you have migrated, use the test cards in the following section to verify your upgraded integration handles 3D Secure authentication.