3DS Server SaaS Integration Manual
3DS Server SaaS Environments
The actual environments for the 3DS Server SaaS product are the payment platform hosted preview and production environments.
Payment Platform Production
This is the live production environment which is connected to the production Directory Servers of the payment schemes / ACS. You can use our Mastercard merchant testing platform if you wish to run production tests with Mastercard cards.
Payment Platform Preview
In this environment you can do integration testing prior migrating to Production. The preview environment has an NDM Simulator installed and configured and contains a Directory Server / ACS simulator with predefined schemes and testing card numbers. The testing card numbers, accepted card ranges and multiple OTP challenges are provided to the customers by Netcetera.
Connection to Preview and Production Environments
The 3DS Server SaaS uses a mutual TLS authentication as a security mechanism. IP whitelisting from our side won’t be needed on the cloud payment platform any longer.
For the communication setup, the following information is needed
| Information | Description |
|---|---|
| CSR | Certificate signing request for TLS communication with the 3DS Server (Netcetera will provide you with the Organization ID) |
| Endpoints | Netcetera will provide you with customer specific endpoints towards the 3DS Server and Admin UI |
| Notification URL domain | The domain the client will use for the Results Response Notification URL |
| Admin email address | A name and an e-mail address for creation of user account for access to the Netcetera Auth and to the Admin UI application |
Connection to the preview and production environments is provided only to customers.
Keystore Operations
The following steps are needed in order to establish a TLS connection with the 3DS Server.
Go to your directory where you would like to store your keys. If you have a Java keystore which already contains other certificates, go to 12.
Generate a new keystore (in JKS format).
- Enter a password (note it for later use)
- For First and Last name enter the Organisation ID provided by Netcetera
- For Organisation Unit you choose what is suitable
- For Organisation enter the name of your company
- For City enter for example the headquarter
- For State / Province enter the state of the headquarter
- For two-letter Country code choose from ISO 3166-1 alpha-2
- Confirm with yes
- Enter password you used before
If you experience the following message: "The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format" execute the following command:
Enter:
and enter your password.Check if private key is in the keystore.
Generate a Certificate Signing Request (CSR) from the keystore:
Check if Common Name (CN) in the CSR contains the Organization ID provided by Netcetera:
Send CSR file to Netcetera.
Export Private key:
Export CRT file from the PEM file received from Netcetera:
Import PEM file to keystore:
Enter:
and enter your password.Check if Netcetera certificate is in the keystore.
Demo - Test Environment
For early access and trial period to the 3DS Server product, you can request to get access to the test environment, which is limited to 1 month testing (NDA must be signed). The testing card numbers, accepted card ranges and multiple OTP challenges are provided by Netcetera during the integration testing. Also provided are a username and password, including getting-started instructions.
This environment is similar to the Payment platform preview environment – i.e. it has an NDM Simulator which mocks DS and an ACS and is used purely for integration testing.
3DS Server Web Service API
Each client has a unique URL for accessing admin and 3ds server applications.
3DS 2.x API
The 3DS Server web services are mapped under /3ds and handle HTTP POST requests. I.e. to initiate authentication, post your request to /3ds/authentication. The request must be HTTPS and must be authenticated with the appropriate certificate.
The 3DS Server provides the following web service operations to support 3-D Secure transactions:
| Operation | Request | Response | Description |
|---|---|---|---|
| versioning | ThreeDSServerVersioningRequest | ThreeDSServerVersioningResponse | Invoke 3DS Method Versioning |
| authentication | ThreeDSServerAuthenticationRequest | ThreeDSServerAuthenticationResponse | Initiate authentication |
| challenge-response | ThreeDSServerFinalCResRequest | ThreeDSServerChallengeResponse | Decode, validate and return challenge response |
| challenge-cancelled | Challenge Cancelled Request | empty response | Notify about challenge cancelled |
| results-response-data | Results Response Data Request | ThreeDSServerResultsResponse | Pull Results Response |
The 3DS Server web service operations can consume/produce the following media types:
application/json
When calling the web service, specify the media type of your content using the Content-Type HTTP header.
Refer to the 3DS Server API documentation for details.
Additionally, the 3DS Server will send requests to the 3DS Requestor, if available, for the following operations:
| Operation | Request | Description |
|---|---|---|
| results | ThreeDSServerResultsResponse | Send the Results Response to the Requestor domain |
The 3DS Server does not require confirmation of the received data from the Requestor, so no data should be returned. The Requestor should ensure that the configured Requestor endpoints are valid and accessible by the 3DS Server. Refer to the 3DS Server API documentation for details.
There is also one web service which handles GET requests and returns paginated stored 3DS Server card ranges:
| Operation | Query Parameters | Response | Description |
|---|---|---|---|
| card-ranges-supported -protocol-versions | page (int, required) size (int, required) | PagePResCardRangeDataEntry | All available card ranges and supported protocol versions |
3DS 1.0 Web Service API
The 3DS 1.0 web services are mapped under /mpi/v1 and handle HTTP POST requests. I.e. to call createPaReqIfEnrolled post your request to /mpi/v1/createPaReqIfEnrolled.
There are two web service operations to support 3-D Secure 1.0 transactions:
| Operation | Request | Response | Description |
|---|---|---|---|
| createPaReqIfEnrolled | PaReqCreationRequest | PaReqCreationResponse | Verifies enrollment with the Directory Server and creates the PaReq to be sent to the ACS. |
| validatePaRes | PaResValidationRequest | PaResValidationResponse | Validates the PaRes returned by the ACS and provides authentication information. |
Media Types
The web service operations can consume the following media types:
application/x-www-form-urlencodedapplication/xmlapplication/json
While they can produce the following media types:
application/xmlapplication/json
When calling the web service, specify the media type of your content using the Content-Type HTTP header and specify the media type you wish to get back in the response using the Accept HTTP header.
Details
Refer to the 3DS 1.0 API documentation for details about the request / response structures and for sample requests.
Union Pay Web Service API
The Union Pay web services are mapped under /upop/v1 and handle HTTP POST requests. I.e. to call createAuthenticationReq post your request to /upop/v1/createAuthenticationReq.
There are three web service operations to support Union Pay transactions:
| Operation | Request | Response | Description |
|---|---|---|---|
| createAuthenticationReq | AuthReqCreationRequest | AuthReqCreationResponse | Creates the MsgReq to be sent to UPOP. |
| validateAuthenticationRes | AuthResValidationRequest | AuthResValidationResponse | Validates the MsgRes returned by UPOP and provides authentication information. |
| inquireAuthenticationStatus | AuthStatusInquiryRequest | AuthStatusInquiryResponse | Inquires UPOP about the status of a transaction |
Media Types
The web service operations can consume the following media types:
application/x-www-form-urlencodedapplication/xmlapplication/json
While they can produce the following media types:
application/xmlapplication/json
When calling the web service, specify the media type of your content using the Content-Type HTTP header and specify the media type you wish to get back in the response using the Accept HTTP header.
Details
Refer to the Union Pay API documentation for details about the request / response structures and for sample requests.ng the web service, specify the media type of your content using the Content-Type HTTP header and specify the media type you wish to get back in the response using the Accept HTTP header.
Netcetera 3DS Web SDK
The Netcetera 3DS Web SDK is a lightweight JavaScript that allows merchants to easily invoke 3DS Method and Challenge Request messages for browser-based transactions.
Installation
To install the Netcetera 3DS Web SDK script simply import the JavaScript in the HTML page.
The Web SDK can be downloaded from
The script will attach the nca3DSWebSDK to the JavaScript window object. The nca3DSWebSDK object contain the following operations:
| Operation | Description |
|---|---|
| init3DSMethod | Creates an HTML structure and attaches a form with a single input (threeDSMethodData) and automatically submits it to the threeDSMethodUrl. |
| createIframeAndInit3DSMethod | Creates an iframe with an HTML structure and attaches a form with a single input (threeDSMethodData) and automatically submits it to the threeDSMethodUrl and attaches the frame to the container. If specified, a callback will be executed when the frame is loaded. |
| init3DSChallengeRequest | Creates an HTML structure and attaches a form with a single input (creq) and automatically submits it to the acsUrl. |
| createIFrameAndInit3DSChallengeRequest | Creates an iframe with an HTML structure and attaches a form with a single input (creq) and automatically submits it to the acsUrl and attaches the frame to the container. If specified, a callback will be executed when the frame is loaded. |
| initiateSPCAuthentication | Initiates Secure Payment Confirmation (SPC) authentication by utilizing the Browser Payment Request API. This shall be done only if the browser supports SPC. The result of the SPC authentication, i.e. the return value of this method should be forwarded in the threeDSRequestorAuthenticationInfo.threeDSReqAuthData field in the second 3DS Server Authentication request. |
Technical documentation on the Netcetera 3DS Web SDK and examples for usage can be found below.
Netcetera 3DS Web SDK Technical documentation
Init 3DS Method Request - Example
Init 3DS Challenge Request - Example