Introduction
The Integration guide set of documents will take you through the process of integrating the 3DS2 flow with a sample merchant checkout site from the beginning, using Java as the backend language.
The sample merchant checkout site provided to is created using Springboot project. For reference, the HTML pages were created using:
The sample merchant checkout page contains three main pages:
index.html
- shopping site for choosing items to purchase.checkout.html
- checkout page containing cardholder information and processing screen.result.html
- transaction result page for viewing if transaction was successful or not.
Prerequisites¶
The following are prerequisites to using this guide:
- Core Java knowledge
- Core web-technologies knowledge (HTML, CSS, Javascript)
- JDK 1.8
- IDE of your choice
- Apache Maven, for installation, please refer to https://maven.apache.org/install.html
- A Git client
- An activated and running ActiveServer instance
Checkout the Sample Code¶
The 3DS Requestor demo code can be found in this Github repository:
https://github.com/gpayments/3ds-requestor-springboot.git
To check out the sample code, execute the following command on your local environment:
1 | git clone https://github.com/gpayments/3ds-requestor-springboot.git |
Once the repository is cloned, you will find all the required demo code of this tutorial under directory 3ds-requestor-springboot
.
To run the sample merchant site¶
The GPayments sample code package above contains two folders:
- initial - Sample merchant checkout page without 3DS2 authentication flow.
- final - Final merchant checkout page with 3DS authentication flow. This will be the final code that you will have at the end of this step-by-step guide.
To run the sample merchant site with 3DS 2.0 authentication enabled, please follow these steps:
Get access to the authentication API client certificate (.p12 file):
- If testing with a local version of ActiveServer - download it from the administration interface under the merchant profile. Please note you need to Activate your ActiveServer Instance first.
- If testing with GPayments TestLabs - use the certificate provided, or contact GPayments if you haven't received your certificate file.
Copy the downloaded certificate (.p12 file) to the filepath
/final/src/main/resources/certs
to allow mutual authentication between the 3DS Requestor and 3DS Server. Please rename the certificate bundle toclient_certificate.p12
so that the demo code can load the p12 file (the file name is hard coded). Please contact GPayments if you encounter problems with activation or certificate downloading.Open a Terminal (Linux) or Command Prompt (Windows) and navigate to
/final
directory.Execute the following command line on the root directory. Please note that this could take a few minutes the first time its executed while Maven downloads the required dependencies.
1 2 | cd final mvn spring-boot:run |
Note
You must ensure Maven is installed and available before running the above command. For Maven installation, please refer to https://maven.apache.org/install.html.
Warning
In Windows you may encounter a Windows Firewall security alert regarding the Java network access. Please allow access to continue.
You can view the sample cart page by accessing http://localhost:8082. Try adding some items to the cart and checkout using the default cardholder information.
Note
If port 8082 is in use you may get an error, in which case configure the port by adding the following line to [/resources/application.properties
] file:
1 | server.port = # YOUR_PORT_NUMBER |
Note
You can also run the initial project which is just an pseudo online shopping site without 3DS 2.0 authentication. To run it, make sure you stop the final
instance (if you run it already) otherwise the port number will be conflicting.
1 2 | cd initial
mvn spring-boot:run
|
Warning
The sample requestor code is running on HTTP just for demo purposes. The code is not suitable for production.
Depending on the package run, the checkout process will complete with either 3DS2 enabled or disabled.
Whats next?
Please select the next button to learn about Front-end implementation for a 3DS Requestor.