Skip to content

Introduction

The Integration guide set of documents will take you through the process of integrating the 3DS2 authentication flow with a sample merchant checkout site from the beginning. This is to implement 3DS Requestor and 3DS Client in the merchant checkout process which is called 3DS Requestor Environment in the EMV 3DSecure 2.0 specification.

This integration guide is based on the provided demo 3DS requestor project which consists of two parts:

  • The HTML/javascript frontend, contains a demo online shop and test pages for BRW, 3RI and Enrol API calls
  • The backend, which hosts the frontend pages and resources as well as performing the page forwarding and calling the ActiveServer authentication API with x509 authentication.

For reference, the frontend web pages and javascript implementation uses the following framework/components:

Prerequisites

The following are prerequisites to using this guide:

Checkout the sample code

The 3DS Requestor demo code is hosted in GitHub and can be cloned from the following repository:

https://github.com/gpayments/gp-3ds-requestor-demo.git

To check out the sample code, execute the following command on your local environment:

1
git clone https://github.com/gpayments/gp-3ds-requestor-demo.git

Once the repository is cloned, you will find all the required demo code of this tutorial under the directory:

1
2
3
$ cd gp-3ds-requestor-demo
gp-3ds-requestor-demo $  ls
dotnet  go  java  php  README.md

GPayments currently provides backend example code for Java, PHP, C#, and Go. Throughout the integration guides, wherever the instructions differ between backend languages a tab will be shown with the relevant instructions.

All backend examples utilise the same front end code, which is written using Javascript and utilises Mustache for templating.

Tip

For simplicity and demo purposes, the demo 3DS Requestor code is implemented with most of the processes and page callback logic in the web frontend code. The backend code remains as a simple server side page forwarding/x509 authentication client to connect with the ActiveServer authentication API. In your actual implementation, you may design and implement your own 3DS Requestor code to fit your existing checkout process and work flow with different frontend and backend code structure.

Server Side Dependencies

For server side 3DS Requestor demo code, depending on different languages, the following dependencies and libraries are required to be installed prior to your first demo 3DS Requestor run:

LanguageDependencies and toolsNotes
JavaJDK 1.8
Apache Maven - https://maven.apache.org/install.html
C#Visual Studio 2013 or later with ASP.NET and web development workload
Nuget is installed, refer to https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools#visual-studio
Windows system required
PHPPHP 7.2 with cURL (Client URL Library)
Composer - https://getcomposer.org
Guzzle - http://docs.guzzlephp.org
OpenSSL
GoGo 1.12 with gin-gonicInstall Go 1.12 from https://golang.org/

Get client certificate

Before the backend can call the ActiveServer authentication API and authenticate itself, a client certificate is required to be setup. With this client certificate, the backend can setup a mutually authenticated TLS connection with ActiveServer.

To obtain the client certificate, refer here.

Copy the downloaded certificate and configure the backend for the location you chose. The client certificate does not have to be in the demo 3DS Requestor directory, however you may find that storing the client certificate within the project may be easier for you to manage.

To check the directory structure of the project, refer to Directory Tree for details.

Demo 3DS Requestor Configuration

To run the demo 3DS Requestor, the following configuration needs to be set before booting up the system:

  1. The 3DS Requestor needs to know the entry point of ActiveServer authentication API and the base url of itself so that it can tell ActiveServer which entry point of the 3DS Requestor to send the callback URLs.

    Configure the AsAuthURL and BaseUrl in your backend resource file. These values will be used when the application is brought up and cannot be changed without restarting the application:

    • AsAuthURL: set to the API URL of your ActiveServer instance.
    • BaseURL: url that the application will be brought up and accessed on.
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    //application.yml
    server:
      port: 8082
    ...  
    gpayments:
      asAuthUrl: https://api.as.testlab.3dsecure.cloud:7443
      baseUrl: http://localhost:8082
      certFileName: # Client Certificate file (.p12 or .pfx) path
      groupAuth: false
      merchantToken: # Your merchantToken when groupAuth = true
    
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    //Web.config
    <appSettings>
    <add key="AsAuthUrl" value="https://api.as.testlab.3dsecure.cloud:7443"/>
    <add key="BaseUrl" value="http://localhost:8082"/>
    <!--Full file name and path of the client certificate (.p12 or .pfx)-->
    <add key="CertFileName" value="certs/clientcert.p12"/>
    <add key="GroupAuth" value="false"/>
    <!--Your MerchantToken when GroupAuth = true-->
    <add key="MerchantToken" value=""/>
    ...
    </appSettings>
    
    //Please note that you may need to configure your IIS listening port to `8082` to match the `BaseUrl` setting in the configuration.
    
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    //application.ini
    asAuthUrl = https://api.as.testlab.3dsecure.cloud:7443
    baseUrl = http://localhost:8082
    ;Client Certificate file (.pem) path generated using openssl command
    certFileName =
    ;Path to Private key path generated using openssl command without password
    keyFileName =
    groupAuth = true
    ; Your merchantToken when groupAuth = true
    merchantToken =
    
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    //application.yml
    server:
     port: 8082
    
    gpayments:
      asAuthUrl: https://api.as.testlab.3dsecure.cloud:7443
      baseUrl: http://localhost:8082
      certFileName: <Full file name and path of the client certificate>
      groupAuth: false
      merchantToken: # Your merchantToken when groupAuth = true
    

    Tip

    If the default port used in the examples is in use you may get an error, in which case configure the port and baseUrl to a suitable value.

  2. Configure the certFileName in your backend resource file to your downloaded certificate:

    • If using a Merchant client certificate:

      • Configure the certFileName to the full filename and path of the downloaded certificate
      • Set groupAuth to false
      • Leave the merchantToken as blank
    • If using a Master Auth API client certificate:

      • Configure the certFileName to the full filename and path of the downloaded certificate
      • Set groupAuth to true
      • Configure the merchantToken. Details of the merchant token can be found here

      Warning

      If groupAuth = true, the back-end needs to add a HTTP Header in the HTTP Request with a field of AS-Merchant-Token which is set to the merchantToken. To check the details of the back-end implementation, refer here.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    //application.yml
    server:
      port: 8082
    ...  
    gpayments:
      asAuthUrl: https://api.as.testlab.3dsecure.cloud:7443
      baseUrl: http://localhost:8082
      certFileName: # Client Certificate file (.p12 or .pfx) path
      groupAuth: false
      merchantToken: # Your merchantToken when groupAuth = true
    
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    //config.cs
    //Web.config
    <appSettings>
    <add key="AsAuthUrl" value="https://api.as.testlab.3dsecure.cloud:7443"/>
    <add key="BaseUrl" value="http://localhost:8082"/>
    <!--Full file name and path of the client certificate (.p12 or .pfx)-->
    <add key="CertFileName" value="certs/clientcert.p12"/>
    <add key="GroupAuth" value="false"/>
    <!--Your MerchantToken when GroupAuth = true-->
    <add key="MerchantToken" value=""/>
    ...
    </appSettings>
    
    //Please note that you may need to configure your IIS listening port to `8082` to match the `BaseUrl` setting in the configuration.
    
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    //application.ini
    asAuthUrl = https://api.as.testlab.3dsecure.cloud:7443
    baseUrl = http://localhost:8082
    ;Client Certificate file (.pem) path generated using openssl command
    certFileName =
    ;Path to Private key path generated using openssl command without password
    keyFileName =
    groupAuth = true
    ; Your merchantToken when groupAuth = true
    merchantToken =
    
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    //application.yml
    server:
      port: 8082
    
    gpayments:
      asAuthUrl: https://api.as.testlab.3dsecure.cloud:7443
      baseUrl: http://localhost:8082
      certFileName: <Full file name and path of the client certificate>
      groupAuth: false
      merchantToken: # Your merchantToken when groupAuth = true
    

    Note

    You can place the client certificate in any location you prefer. For example, for a client certificate file located in the C:/Downloads directory (for windows platforms) with the file name client_certificate.p12, you should change the certFileName to be C:/Downloads/client_certificate.p12.

    Note: For PHP, please follow the instruction here to extract the private key and certificate.

  3. Open a Terminal (Linux, for Java, PHP or Go), Command Prompt (Windows, for Java, PHP or Go) or Developer Command Prompt (Windows, for C#) and execute the following command line on the root directory of the project. Note that this could take a few minutes the first time it is run if any dependencies are required to be download:

    1
    2
    $ cd java
    $ mvn spring-boot:run
    
    1
    2
    > cd dotnet
    > startup.bat
    
    1
    2
    3
    4
    $ cd php
    $ curl -sS https://getcomposer.org/installer | php
    $ php composer.phar install
    $ php -S localhost:8082
    
    1
    2
    $ cd go
    $ go run .     
    

    Firewall warnings for Java Network access in Windows

    In Windows you may encounter a Windows Firewall security alert regarding the Java network access, allow access to continue.

View 3DS Requestor website

Once the client certificate and the URLs are configured properly, and the startup command has been executed, the demo 3DS Requestor should be started up successfully. You can view the 3DS Requestor page by accessing http://localhost:8082 (or the BaseURL specified above):

index site

Select the Launch button under Online shop to open the shop page. Try adding some items to the cart and checkout using the default cardholder information:

purchase page

The demo 3DS Requestor then shows the checkout page:

checkout page

Proceed with the Contine to Checkout button, the demo 3DS Requestor will show the progress screen:

progress page

Then finally show the result page (note depending on the card number used, you may be prompted for a challenge screen, check Sample code feature for details):

checkout page

Congratulations! You just successfully ran and tested your first demo 3DS Requestor locally.

Warning

You may notice that the demo 3DS Requestor is running on HTTP. This is just for demo purposes and this code is not suitable for production.

Support

If you have any questions for reading this documentation, we are here to help. Please email us at techsupport@gpayments.com.

Whats next?

Select the next button to learn about the Front-end implementation for a 3DS Requestor.