Authenticate payments with 3D Secure

• You've completed theGetting started with the Storefront APIguide.

• You're familiar withquerying products and collections.

• If instead of completing theGetting started, you'veturned your app into a sales channelandrequested and been approved for payment processing.

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

• You'vecreated a checkout with the Storefront API.

下面的图显示了the general workflow that you can follow to authenticate payments that require 3D Secure authentication.

1. The app completes the checkout and receives thenextActionUrlattribute of thePaymentobject.

2. If thenextActionUrlisnull,然后客户不需要身份验证.

   If thenextActionUrlisn'tnull, then the app redirects the customer to thenextActionUrlto complete authentication.

3. The app polls the payment untilreadyreturnstrue.

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

You can pass the checkout ID, payment information, and session ID to thecheckoutCompleteWithCreditCardV2mutation to complete a checkout. For more information about creating and completing a checkout, refer toCreate a checkout with the Storefront API.

The following example shows a request and response for thecheckoutCompleteWithCreditCardV2mutation. Make note of thenextActionUrlin the response, which you'll use to poll the payment inthe next step.

ThenextActionUrlfield 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 thenextActionUrlisnull, then the customer doesn't need to authenticate their payment.

After you've sent your customer to thenextActionUrl, your app needs to poll the payment. ThePaymentobject includes thereadyfield, which is a Boolean that indicates whether the payment is still processing asynchronously. Theready场仍falseuntil authentication is completed with either a success or failure.

Your app should continue to poll the payment until thereadyfield returnstrue. Whenreadyistrue, the payment has reached a final state and nothing further will change. At this point, thecompletedAtfield on the checkout returns a time for a successful payment, ornullfor 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:

• nextActionUrlalways returnsnull. If you continue to poll the token, then thereadyfield eventually returnstruewhen the payment has completed its asynchronous processing.
• If the payment succeeds, then the checkout'scompletedAtfield is updated with the time of completion.
• If the payment fails, then the checkout'scompletedAt场仍null, anderrorMessagecontains a payment processing error message.

If thePaymentobject includes anextActionUrlfield, but doesn't handle the redirect within ten minutes, then Shopify marks the authentication as an error, and returns an error message.