Customer authentication by using the 3‑D Secure 1

Overview

Customer authentication by using the 3‑D Secure (Three-Domain Secure) is intended to secure e-commerce payments performed by using cards. You can use 3‑D Secure with different customer authentication methods, for example the most common used is one-time verification code—(One Time PIN, OTP). Normally, a customer receives a one-time code via SMS and types the code on the authentication page.

3‑D Secure uses three domains:

  • Acquirer domain In the context of the ECommPay payment platform interoperability, it includes merchant web service, the payment platform, and its Merchant Plug-In Server (MPI Server), and a provider if it is involved in the authentication process.
  • Interoperability domain The infrastructure provided by the card scheme, for instance Directory Server (DS).
  • Issuer domain This includes the issuer's Access Control Server (ACS).

The domains exchange messages that are required to authenticate customer. In the first version of the 3‑D Secure protocol, these messages include: Verifying Enrolment Request (VEReq) and Verifying Enrolment Response (VERes), as well as Payer Authentication Request (PAReq) and Payer Authentication Response (PARes).

Please note that information about the possibility of customer authentication is stored on the Access Control Server, and therefore this information can only be obtained after sending a payment request. Also, the payment platform does not have control over customer actions on the authentication page, but only receives the authentication result.

When performing a customer authentication by using the 3‑D Secure 1 technology, the merchant web service is required to do the following:

  1. Accept a callback or callbacks the payment platform sent that requests 3‑D Secure 1 authentication.
  2. Respond with the 200 OK response.
  3. Send the request to the issuer URL by using the information contained in callback (PAReq), in order to redirect the customer to the authentication page.
  4. If necessary, accept a callback the issuer sent with the authentication results (PARes) and send the request with the results to the payment platform.

The sections that follow discuss in more details the request format and parameters required to continue payment processing with a customer authentication by using 3‑D Secure 1.

Workflow

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

The payment platform requests the 3‑D Secure 1 authentication in callbacks with customer redirection data. Then, the web service needs to respond with the 200 OK response and properly react to callbacks obtained from the payment platform. The reaction to the callbacks with customer redirection data depends on payments, providers, and the information the callbacks contain:

  • If the parameter set inside the callback body contains the acs object, you need to redirect the customer to the authentication page—issuer's Access Control Server(ACS), accept the authentication result from the issuer's ACS and send the payment completion request with the result to the payment platform. After the payment platform discovers that the 3‑D Secure 1 authentication is required, it waits for the payment completion request with the authentication result; normally, the waiting time is 30 minutes. If the payment platform does not receive the request with the authentication result within this waiting time, the payment is automatically declined.
  • If the parameter set inside the callback body contains the redirectData object, you need to redirect the customer to the page hosted on the provider side. After that, you are not required to do anything more with authentication. For more information about when the payment platform use that object, refer to your ECommPay key account manager.
When you submit the authentication result, the payment platform continues payment processing and optionally may request the 3‑D Secure 1 authentication in additional one or more callbacks. If the additional callback contains the cascading_with_redirect parameter that is set to true, the web service is required to do the following:
  • Display an error message to a customer on a page and obtain user consent to re-authenticate.
  • Repeat the previous step by following one of two reactions.
For more information about additional callbacks, refer to the ECommPay support service at support@ecommpay.com.

Figure: Basic workflow

  1. The payment platform processes the request and determines whether the 3‑D Secure 1 authentication is required.
  2. The payment platform queries the MPI Server whether 3‑D Secure 1 authentication is supported.
  3. The MPI Server forwards the request to the Directory Server.
  4. The Directory Server forwards the request to the Access Control Server.
  5. The Access Control Server checks whether the 3‑D Secure 1 authentication is supported.
  6. The Access Control Server sends message that the 3‑D Secure 1 authentication is supported.
  7. The Directory Control Server sends the customer redirection data to the MPI.
  8. The MPI sends the customer redirection data to the payment platform.
  9. The payment platform sends the callback with the customer redirection data to the merchant web service.
  10. The web service sends acknowledge message to the payment platform.
  11. The web service redirects customer to the issuer's authentication page.
  12. The authentication page is displayed to the customer.
  13. The Access Control Server authenticates the customer.
  14. The Access Control Server redirects the customer to the web service and sends a message with the authentication results to the payment platform.
  15. 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.

Figure: Workflow that is involved provider

  1. The provider processes the request.
  2. The provider sends the message with the customer redirection data to the payment platform.
  3. The payment platform sends the message with the customer redirection data to the merchant web service.
  4. The web service sends acknowledge message to the payment platform.
  5. The web service redirects customer to the issuer's authentication page via the provider service.
  6. The authentication page is displayed to the customer.
  7. The issuer authenticates the customer.
  8. The issuer redirects the customer to the web service.
  9. The web service payment page is displayed to the customer.

For general information about the Gate API, see Interaction concepts.

Format of callback with redirection data

In the authentication workflow, the payment platform sends a callback with customer redirection data as described in more details in Callbacks. The redirection data is specified in the acs or redirectData objects.

The acs includes the PAReq message, the address of the authentication page, and merchant data stored in the payment system.

Figure: Sample redirection data that the acs object contains

"acs":{  
  "pa_req":"eJxVUtluwyAQ/BUrH2DA...n8/4htjT7Em", // PAReq message
  "acs_url":"https://example.com/ACS",
                              // The authentication page URL
  "md":"eyJfto7jg456ZCI6IiJ9" // Merchant data in the payment system
}

The redirectData includes the request body, the request sending method, and the provider URL.

Figure: Sample redirection data that the redirectData object contains

"redirectData":{
  "method":"GET",
  "body":[  ],
  "encrypted": [  ],
  "url":"https://example.com/..."
}

Format of the customer redirection data

To redirect a customer from the web service to the issuer's or provider page, you must receive a callback from the payment platform that contains the redirection data and send the request by using the POST or GET method. The parameter set inside the request body depends on the redirection data inside the request body and contains the following:

  • If you accept the callback with the acs object:
    • action—an issuer URL (ACS URL) that the ECommPay payment platform submitted with the acs_url parameter of a callback.
    • PaReq—a PAReq message, that the ECommPay payment platform submitted with the pa_req parameter of a callback.
    • TermUrl—the web service URL. When a customer authentication completed, an issuer redirects a customer to this web service URL.
    • MD—information about merchant that the ECommPay payment platform submitted with the md parameter of a callback.

    The request sending method is POST.

  • If you accept the callback with the redirectData object:
    • action—a provider URL that the ECommPay payment platform submitted with the url parameter of a callback
    • method — the request sending method
    • body — object that contains the request body

Figure: Sample HTML page code that the acs object contains

<form id="3dsform" action="https://example.com/ACS" method="post" enctype="application/
x-www-form-urlencoded">
    <input type="hidden" name="PaReq" value="eJxVUtluwyAQ/BUrH2DA...n8/4htjT7Em" />
    <input type="hidden" name="TermUrl" value="http://example.com/termurl" />
    <input type="hidden" name="MD" value="eyJfto7jg456ZCI6IiJ9" />

</form>
<script type="text/javascript">
    setTimeout(function() {
        document.getElementById("3dsform").submit();
    }, 1000);
</script>

You can use our ready-made Example of the HTML file for customer authentication process contained request that is required to send to an issuer for initiating a customer authentication. But you replace each test value with actual one.

Format of payment completion request

When you process payment by using Gate, after the authentication procedure is successfully completed, you need to send to the payment platform a request to complete the payment procedure and transfer actual money. You must create and send the request to the /v2/payment/card/3ds_result endpoint by using POST (HTTP) method. The request must contain the following objects and parameters:

  • Object general—general request identification information:
    • project_id—the project ID obtained from ECommPay
    • payment_id—payment ID unique within the project
    • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
  • Parameter pares—a PARes message with the customer authentication by using 3-D Secure result

In other words, a valid request for payment completion after the 3‑D Secure 1 authentication is complete must contain project ID, payment ID, signature and authentication result message.

Figure: Sample payment completion request

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "pares": "eJzVWdfvq8iy/iujOY/WDBnbI+9ldZMMJpho4I1...Dfn76en3N+f/A1fJrSU="
}