Authenticate payments with 3D Secure

• You've completed the Getting started with the Storefront API guide.

• You're familiar with querying products and collections.

• If instead of completing the Getting started, you've turned your app into a sales channel and requested and been approved for payment processing.

• You've familiarized yourself with the concept of payment authentication with 3D Secure

The following diagram shows the general workflow that you can follow to authenticate payments that require 3D Secure authentication.

1. The app completes the checkout and receives the nextActionUrl attribute of the Payment object.

2. If the nextActionUrl is null, then the customer doesn't require authentication.

   If the nextActionUrl isn't null, then the app redirects the customer to the nextActionUrl to complete authentication.

3. The app polls the payment until ready returns true.

4. The app redirects the customer back to the app.

You can pass the checkout ID, payment information, and session ID to the checkoutCompleteWithCreditCardV2 mutation to complete a checkout.

The following example shows a request and response for the checkoutCompleteWithCreditCardV2 mutation. Make note of the nextActionUrl in the response, which you'll use to poll the payment in the next step.

The nextActionUrl field contains the URL where the customer needs to be redirected so they can complete the 3D Secure payment flow. Your app needs to send the customer to this URL so that they can authenticate their payment.

If the nextActionUrl is null, then the customer doesn't need to authenticate their payment.

After you've sent your customer to the nextActionUrl, your app needs to poll the payment. The Payment object includes the ready field, which is a Boolean that indicates whether the payment is still processing asynchronously. The ready field remains false until authentication is completed with either a success or failure.

Your app should continue to poll the payment until the ready field returns true. When ready is true, the payment has reached a final state and nothing further will change. At this point, the completedAt field on the checkout returns a time for a successful payment, or null for a payment that fails to complete. If the payment fails, then an error message is returned.

The following example shows how to poll a payment, which informs you if the payment has completed processing:

After the authentication is completed, the customer is redirected to a processing page. Your app is responsible for closing the page or webview after the authentication is completed and redirecting the customer back to your app.

For payments that don't require 3D Secure, there aren't any changes to the app or sales channel’s behavior:

• nextActionUrl always returns null. If you continue to poll the token, then the ready field eventually returns true when the payment has completed its asynchronous processing.
• If the payment succeeds, then the checkout's completedAt field is updated with the time of completion.
• If the payment fails, then the checkout's completedAt field remains null, and errorMessage contains a payment processing error message.

If the Payment object includes a nextActionUrl field, but doesn't handle the redirect within ten minutes, then Shopify marks the authentication as an error, and returns an error message.