Migrating to Payment Intents

Server-side confirmation

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:

1. Update your API version and your client library.
2. 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.
3. Migrate your existing Charges API integration on Web, iOS, and Android to use the Payment Intents API.
4. Migrate your integration that saves cards on Customer objects.
5. 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_source has been renamed to requires_payment_method
• requires_source_action has been renamed to requires_action

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:

stripe.createToken(
// or stripe.createSource
  cardElement
).then(function(result) {
  if (result.error) {
    // Show error in payment form
  } else {
    // Send token.id to server
    fetch('/ajax/confirm_payment', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        token_id: result.token.id
      })
    }).then(function(result) {
      // Handle server response (see Step 3)
      result.json().then(function(json) {
        handleServerResponse(json);
      })
    });
  }
});

stripe.createPaymentMethod({
  type: 'card',
  card: cardElement
}).then(function(result) {
  if (result.error) {
    // Show error in payment form
  } else {
    // Send paymentMethod.id to server
    fetch('/ajax/confirm_payment', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        payment_method_id: result.paymentMethod.id
      })
    }).then(function(result) {
      // Handle server response (see Step 3)
      result.json().then(function(json) {
        handleServerResponse(json);
      })
    });
  }
});

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

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method"="{{PAYMENT_METHOD_ID}}" \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "confirmation_method"="manual" \
  -d "confirm"="true"

# If status == 'requires_action' and
# next_action.type == 'use_stripe_sdk'
# -> Tell the client to handle the action
#
# If status == 'succeeded'
# -> The payment didn't need any additional actions and completed!
# -> Handle post-payment fulfillment

function handleServerResponse(response) {
  if (response.error) {
    // Show error on payment form
  } else {
    // Show success message
  }
}

function handleServerResponse(response) {
  if (response.error) {
    // Show error from server on payment form
  } else if (response.requires_action) {
    // Use Stripe.js to handle required card action
    handleAction(response);
  } else {
    // Show success message
  }
}

function handleAction(response) {
  stripe.handleCardAction(
    response.payment_intent_client_secret
  ).then(function(result) {
    if (result.error) {
      // Show error in payment form
    } else {
      // The card action has been handled
      // The PaymentIntent can be confirmed again on the server
      fetch('/ajax/confirm_payment', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          payment_intent_id: result.paymentIntent.id
        })
      }).then(function(confirmResult) {
        return confirmResult.json();
      }).then(handleServerResponse);
    }
  });
}

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.

stripe.createToken(
// or stripe.createSource
  cardElement
).then(function(result) {
  if (result.error) {
    // Display result.error.message in UI
  } else {
    // Send result.token to server
  }
});

stripe.createPaymentMethod({
  type: 'card',
  card: cardElement,
}).then(function(result) {
  if (result.error) {
    // Display result.error.message in UI
  } else {
    // The PaymentMethod has successfully
    // been created
  }
});

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/charges \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{TOKEN_OR_SOURCE}}" \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "customer"="{{CUSTOMER_ID}}"

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method"="{{PAYMENT_METHOD_ID}}" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "confirmation_method"="manual" \
  -d "confirm"="true" \
  -d "setup_future_usage"="off_session"

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.

customer.sources

curl https://api.stripe.com/v1/payment_methods?customer={{CUSTOMER_ID}}&type=card \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

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.

Use these cards in your application or the payments demo to see the different behavior.

Next steps

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: