How to take PaymentIntents into use
Overview of how Stripe PaymentIntents work in FTW, and how you can change older FTW version to support for Strong Customer Authentication (SCA).
This guide walks you through the process of taking PaymentIntents into use. Stripe's PaymentIntent is a new way to handle Strong Customer Authentication (SCA) by using frictionless 3D Secure 2 authentication.
Note: Taking Stripe PaymentIntent flow into use, is a big change for CheckoutPage and includes process change. You should carefully check what kind of changes are made in FTW release: v3.0.0. Taking update from upstream or even cherry-picking commits might make the update easier, but you should first track your custom-code to affected components.
Stripe's Payment Intents API is a new way to build dynamic payment
automatic confirmation flow
helps a lot since all the authentication actions for a customer are
included in a single call:
stripe.handleCardPayment. When called,
Stripe's SDK checks if there's a need for Strong Customer Authentication
(SCA) and creates a popup to card issuer's website.
However, to be able to call
handleCardPayment, there needs to be a new
state to the transaction process. Because of this, we have split the
previous transition (Initial - request -> Preauthorized) into two:
So, after transitions (
request-payment-after-enquiry), API returns
stripePaymentIntentClientSecret among the protected data of the
current transaction. This client-secret is used for the call to
stripe.handleCardPayment. Then there is another transition made
against Marketplace API, so that it can confirm the PaymentIntent and
preauthorize the order. Transaction process continues normally after
that - i.e. Provider has to accept or reject the order.
Concrete steps here are changing the transaction process, then updating
config.js and making necessary changes to
src/util/transaction.js file. Remember, when transaction process is
changed, you need to go through all the files that import transitions or
utility functions from
util/transaction. In practice, we made changes
to InboxPage, TransactionPage, TransactionPanel, ActivityFeed,
BookingBreakdown, BookingDatesForm, and CheckoutPage. The list
might be different if you have customized your components or process.
The default transaction process supports SCA, but if you have an older process version without PaymentIntents, you can see our new example processes here:
All the example processes support SCA. If you need help with the concrete steps to customize your process to support SCA, contact Flex support from the support widget in Console and we'll guide you through the changes.
When using PaymentIntent flow, we don't need
anymore, but we need to add two new thunk calls:
stripe.handleCardPayment is needed to provide SCA as mentioned
earlier. However, since customers are making several AJAX calls on
CheckoutPage, it is possible that there is a network error or
something else happening between those calls. Even the whole page, might
be reloaded at some point. We need to retrieve up-to-date PaymentIntent
from Stripe API and check its status to be able to continue the payment
process. This can be done with
The biggest change happens in CheckoutPage. When a user submits
handleSubmit is called from CheckoutPage, new
data needs to be prepared (billing details: name, email, and billing
address) and then 4 thunk-calls/Promises need to be made in sequence:
This tells Marketplace API to create booking and PaymentIntent
- Booking is created, so availability management blocks dates for conflicting bookings
- API returns
stripePaymentIntentClientSecretinside transaction's protectedData
This combines both transitions:
sdk.transitions.transitionaka continue enquiry with
- Automatic expiration happens in 15 minutes, if process is not
- Created transaction is saved to session storage or existing enquiry tx is updated. (There is more about this step later.)
- This is a call
- If the customer must perform additional steps to complete the payment, such as authentication, Stripe.js walks them through that process.
- This tells Marketplace API that customer has completed the payment requirements. API will validate and mark the payment confirmed in Flex.
- If the customer has added an initial message to the provider, the app sends that message after the payment is confirmed.
stripe.handleCardPaymentneeds an instance of Stripe to be passed from StripePaymentForm.
stripe.handleCardPaymentwill check card details from connected Stripe Elements input.
We use session storage to buffer checkout page against page reloads and errors - customer needs to be able to continue payment after accidental page refresh and network errors. This is a UX issue, but more importantly, it builds trust. Because of this need, we save booking dates and other data there. Previously enquiredTransaction was saved there too, but that concept is now expanded a bit: any transaction can now be saved to session storage under the key "transaction".
So, if there is an existing transaction in enquiry state and customer
books the listing, TransactionPage sends that
CheckoutPage. As a first step CheckoutPage saves received data to the
session store. This is pretty much the same functionality as with
previous card-token payment process - only the key is changed from
enquiryTransaction to transaction. However, after transition
request-payment-after-enquiry) the updated
transaction is saved again. (the relevant new data in transaction is
In addition, the handling of booking breakdown with
SpeculatedTransaction needs to be changed because saved transaction
already contains booking in some cases and a new call to
sdk.transactions.initiateSpeculative would just return a conflict
error telling about an already existing booking.
Most of the visual changes happen in StripePaymentForm. Billing details are added to the form and most of the errors of different thunk calls are shown inside it.
The default mode for FTW is to show billing address fields. Even though
it is recommended by Stripe, you might want to remove those fields due
to UX reasons. That can be made just by not adding
Note: if the page is reloaded after successful call to
stripe.handleCardPaymentbilling details should not be shown to the user since credit card number and other billing details are already sent to Stripe.
Since 3D Secure authentication flow is different between different credit card issuers, you should test at least some credit cards how they work in a live environment.
This can be done by creating another Heroku instance (or some other production environment) that uses your production Client Id for Flex with live Stripe keys (both publishable and secret). Then create a new Git branch that takes PaymentIntents flow into use and adds Basic Authentication configuration into environment variables. After that, you could deploy your payment-intent branch into Heroku (or your alternative production environment). Then you can just book some existing listing and maybe reject it to get refund to your live card account.