Authentication workflows

3‑D Secure 2 workflow in Payment Page

In the ECommPay payment platform, you can use the 3‑D Secure 2 authentication in one-step and two-step payments with cards and in payment instrument verification with cards.

The 3‑D Secure 2 authentication requires you to send a request with the required parameters and the signature to the ECommPay interface URL and accept the callback with payment result.

If the 3‑D Secure 2 authentication procedure fails because the payment system or the issuer is unavailable or the issuer does not support 3‑D Secure 2, the payment platform falls back to 3‑D Secure 1 and retries the authentication procedure. This situation does not require any additional effort on the part of the web service, though note that your customer may be confused when receiving both a "payment rejected" message and a new verification code and a "payment was successful" message.

Here is a diagram of the 3‑D Secure 2 authentication workflow in a one-step payment procedure.

Figure: The 3‑D Secure 2 authentication workflow

  1. The payment platform processes the request and determines whether the 3-D Secure authentication is required.
  2. The payment platform queries the 3DS Server what 3-D Secure authentication version (or versions) is supported.
  3. The 3DS Server checks whether the chosen authentication version is supported.
  4. The 3DS Server sends a callback with an iframe data to the payment platform.
  5. The payment platform forwards the iframe data to Payment Page.
  6. Payment Page opens the iframe.
  7. The iframe script collects customer device fingerprint data and sends the device fingerprint to issuer's Access Control Server.
  8. The Access Control Server sends to Payment Page a callback in which acknowledges receiving the data.
  9. Payment Page sends the authentication initiation request to the payment platform.
  10. The payment platform sends the authentication request to the 3DS Server.
  11. The 3DS Server forwards the request to the Directory Server.
  12. The Directory Server forwards the request to the Access Control Server.
  13. The issuer authenticates the customer. If the issuer chooses the frictionless flow, the Access Control Server sends a message with the authentication results to the payment platform (the message is forwarded through the Directory Server and the 3DS Server). If the issuer chooses the challenge flow, the authentication follows these steps:
    • The Access Control Server sends a message with the URL for redirecting customer to the authentication page to the Payment Page through the Directory Server, the 3DS Server and the payment platform.
    • The customer is redirected to the authentication page.
    • The customer is presented with the authentication page and enters all the information required for the authentication.
    • The issuer authenticates the customer.
    • The Access Control Server sends a message with the authentication results to the 3DS Server through the Directory Server.
    • The 3DS Server sends the message acknowledgement to the Access Control Server through the Directory Server.
    • Customer is redirected to Payment Page along with the authentication result.
    • The Payment Page preload page is displayed to the customer.
    • Payment Page sends the payment completion request to the payment platform.

For information about request and callback formats used in the 3‑D Secure 2 procedure, see Communication formats. For general information about the Payment Page API, see Payment Page API Description.

3‑D Secure 2 workflow in Gate

In the ECommPay payment platform, you can use the 3‑D Secure 2 authentication in one-step and two-step payments with cards and in payment instrument verification with cards. The payment platform supports frictionless and challenge authentication workflows in Gate payments.

Basic workflow

The 3‑D Secure 2 authentication requires your web service to do the following:

  1. Accept the callback with the customer redirection data from the payment platform and send the callback receipt acknowledgment.
  2. Redirect the customer to the payment platform preload page by using the information contained callback.
  3. Accept the message with authentication result from the payment platform.
  4. Send request for payment completion to the /v2/payment/card/3ds_result.

If the 3‑D Secure 2 authentication procedure fails because the payment system or the issuer is unavailable or the issuer does not support 3‑D Secure 2, the payment platform falls back to 3‑D Secure 1 and retries the authentication procedure. This situation does not require any additional effort on the part of the web service, though note that your customer may be confused when receiving both a "payment rejected" message and a new verification code and a "payment successful" message.

Here is the diagram of the basic 3‑D Secure 2 authentication workflow in a one-step purchase.

Figure: The basic 3‑D Secure 2 authentication workflow

  1. The payment platform processes the request and determines whether the 3-D Secure authentication is required.
  2. The payment platform requests from the 3DS Server what 3-D Secure authentication versions are supported.
  3. 3DS Server checks what 3-D Secure authentication version is supported.
  4. 3DS Server sends the customer redirection data to the payment platform.
  5. The payment platform sends the customer redirection data to the merchant web service.
  6. The web service sends acknowledge message to the payment platform.
  7. The web service redirects customer to the preload page hosted on the payment platform.
  8. The preload page hosted on the payment platform is displayed to the customer.
  9. The payment platform opens the iframe.
  10. The iframe script collects customer device fingerprint data and sends the device fingerprint to issuer's Access Control Server.
  11. The Access Control Server sends to the payment platform a callback in which acknowledges receiving the data.
  12. The payment platform sends the customer authentication request to the 3DS Server.
  13. The 3DS Server sends the customer authentication request to the Directory Server.
  14. The Directory Server forwards the request to the Access Control Server.
  15. The issuer authenticates the customer. If the issuer chooses the frictionless flow, the Access Control Server sends a message with the authentication results to the payment platform (the message is forwarded through the Directory Server and the 3DS Server) and the customer is redirected to the web service. If the issuer chooses the challenge flow, the authentication follows these steps:
    • The Access Control Server sends a message with the URL for redirecting customer to the authentication page to the payment platform through the Directory Server and the 3DS Server.
    • The customer is redirected to the authentication page.
    • The customer is presented with the authentication page and enters all the information required for the authentication.
    • The issuer authenticates the customer.
    • The Access Control Server sends a message with the authentication results to the 3DS Server through the Directory Server.
    • The 3DS Server sends the message acknowledgement to the Access Control Server through the Directory Server.
    • The customer is redirected to the preload page hosted on the payment platform.
    • The preload page hosted on the payment platform is displayed to the customer.
    • Customer is redirected to the web service along with the authentication result.
    • The preload page hosted on the web service is displayed to the customer.
  16. The web service sends request for payment completion that contains the authentication result to the URL of the ECommPay payment platform.
  17. The payment platform accepts the request.
  18. The payment platform validates and then processes the request.
  19. The payment platform sends the response with the validity check result and the request receipt acknowledgement.

For information about request and callback formats used in the basic 3‑D Secure 2 authentication workflow, see Communication formats. For general information about the Gate API, see Interaction concepts.

Extended workflow

In the extended authentication worlflow, you can use the 3ds_notification_url parameter in order to receive a callback in which acknowledges receiving customer's device fingerprint from the Access Control Server.

The 3‑D Secure 2 authentication requires your web service to do the following:

  1. Accept the callback with the iframe data from the payment platform and send the callback receipt acknowledgment.
  2. Open the iframe by using the information contained in the callback.
  3. If the payment initiation request contains the 3ds_notification_url parameter, the web service is required to accept the acknowledgement message from the issuer's Access Control Server and send the authentication initiation request to the payment platform. If the payment initiation request does not contain the parameter, the web service is required to skip this step.
  4. If the issuer chooses the frictionless flow, the web service is required to accept a callback with the authentication result from the payment platform. If the issuer chooses the challenge flow, the web service is required to complete the following steps:
    • Accept the callback contained information for redirecting customer to the authentication page from the payment platform and respond with the callback acknowledgement to the payment platform.
    • Redirect the customer to the authentication page.
    • Accept the authentication result.
    • Send request for payment completion that contains the authentication result in the 3ds_result parameter.

In some cases, the issuer may decide to authenticate the customer before receiving customer's device fingerprint. In this case, your web service needs to follow the standard payment workflow and receives the authentication result inside the callback with the payment result from the payment platform.

If the 3‑D Secure 2 authentication procedure fails because the payment system or the issuer is unavailable or the issuer does not support 3‑D Secure 2, the payment platform falls back to 3‑D Secure 1 and retries the authentication procedure. The payment platform can retry the authentication procedure at any time, even after redirecting the customer to the authentication page In this case, your web service needs to accept and process a callback with customer redirection data as described in Customer authentication by using the 3‑D Secure 1. Also, note that your customer may be confused when receiving both a "payment rejected" message and a new verification code and a "payment was successful" message.

Here is the diagram of the extended 3‑D Secure 2 authentication workflow in a one-step purchase. The workflow includes two authentication flows—frictionless and challenge flows—and two ways the Access Control Server sends a callback in which it acknowledges receiving customer's device fingerprint—to the web service and to the payment platform.

Figure: The extended 3‑D Secure 2 authentication workflow

  1. The payment platform processes the request and determines whether the 3‑D Secure is required.
  2. The payment platform queries the 3DS Server what 3-D Secure authentication versions are supported.
  3. The 3DS Server checks what 3-D Secure authentication version is supported.
  4. The 3DS Server sends the iframe data to the payment platform.
  5. The payment platform sends the iframe data to the web service.
  6. The web service sends acknowledge message to the payment platform.
  7. The web service opens the iframe.
  8. The iframe script collects the data about customer device and sends it to issuer's Access Control Server.
  9. If the payment initiation request contains the 3ds_notification_url parameter, the Access Control Server sends to the web service a callback in which acknowledges receiving the data. Otherwise, the Access Control Server sends to the payment platform the callback. In the first case the authentication follows the following steps:
    • Web service sends the authentication initiation request to the ECommPay URL.
    • The payment platform accepts the request.
    • The payment platform validates and then processes the request.
    • The payment platform sends the response with the validity check result and the request receipt acknowledgement.
  10. The payment platform forwards the authentication request to the 3DS Server.
  11. The 3DS Server forwards the request to the Directory Server.
  12. The Directory Server forwards the request to the Access Control Server.
  13. The issuer authenticates the customer. If the issuer chooses the frictionless flow, the Access Control Server sends a message with the authentication results to the payment platform (the message is forwarded through the Directory Server and the 3DS Server). If the issuer chooses the challenge flow, the authentication follows the following steps:
    • The Access Control Server sends a message with the URL for redirecting customer to the authentication page to the payment platform through the Directory Server and the 3DS Server.
    • The payment platform sends the customer redirection data to the web service.
    • The customer is redirected to the authentication page.
    • The customer is presented with the authentication page and enters all the information required for the authentication.
    • The issuer authenticates the customer.
    • The Access Control Server sends a message with the authentication results to the 3DS Server through the Directory Server.
    • The 3DS Server sends the message acknowledgement to the Access Control Server through the Directory Server.
    • The customer is redirected to the web service and the authentication result is sent to the web service.
    • The preload page hosted on the web service is displayed to the customer.
    • The web service sends the request for payment completion that contains the authentication result to the ECommPay URL.
    • The payment platform accepts the request.
    • The payment platform validates and then processes the request.
    • The payment platform sends the response with the request receipt acknowledgement and the validity check result to the web service.

For information about request and callback formats used in the extended 3‑D Secure 2 authentication workflow,see Communication formats. For general information about the Gate API, see Interaction concepts.