3DS Server SaaS Integration Manual

3DS Server SaaS Environments

Netcetera provides cloud payment platform hosted preview and production environments for the 3DS Server SaaS product .

We are using world leading hosting service providers and ensuring our customers receive exceptional service performance service through a highly secure, scalable and available infrastructure.

Production Environment

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.

Preview Environment

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

Netcetera provides two different authentication methods for establishing secure connection between customers and Netcetera environments. The customers can select an authentication method based on the preference.

Mutual TLS authentication

The 3DS Server SaaS uses a mutual TLS authentication as a security mechanism.

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.

Please ensure that you are trusting all root certificates of AWS and you are following the recommendations of AWS described at: Amazon Trust Services Repository

OAuth Client Credentials Grant

NOT available for new customers

The Client Credentials Grant is a type of OAuth 2.0 authentication grant that allows a client (an application or service) to authenticate directly with the authorization server using its own credentials.

OAuth Client Credentials Grant process:

The authentication process shall be initiated by requesting an access token from the Netcetera Identity Service, using the Client ID and Client Secret (Netcetera will provide you the Client ID and Client Secret). The Client ID and Client Secret need to be sent in an Authorization header as Basic auth, where the final value is Base 64 encoded value(client_id:client_secret). Example header: Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= Besides the Authorization header, the Content-Type header needs to be passed with the value of "application/x-www-form-urlencoded". The following x-www-form-urlencoded parameters need to be sent:
```
- "grant_type": "client_credentials"
```
Finally, the request should look like:
Netcetera Identity Service verifies the credentials and responds with a signed JWT. The response from calling the endpoint would be in JSON format:
Although "refresh_expires_in", "scope" and "not-before-policy" are included in the response, these fields are not used in this case.
The access token must be stored and utilized until expiration. Once the token validity expires, new access token should be requested by following the same process mentioned in step 1. Additionally, it is a customer responsibility to securely store and keep track of the validity of the access token.
Once the token is obtained, it can be used for sending request to the 3DS Server. For performing the necessary authorization, these requests must include the "Authorization: Bearer ACCESS_TOKEN" header.

It is highly recommended the token to be utilised until its expiration date instead of using a new token for every individual request. Making frequent token requests would considerably slow down the overall execution of the requests directed towards the 3DS Server.

A diagram illustrating the handling process of the token by the client's services:

Access token flow diagram

Tokens can be invalidated using a revoke endpoint. (The revoke endpoint will be provided by Netcetera). When revoking a token, the customer must use the Client ID and Client Secret to authenticate to the Netcetera Identity Service. Once the token is revoked, it becomes inactive and any transaction used with that token will fail.

Netcetera Identity for Admin UI users

The user management is in your hands so that you can operate more flexible and independently. For this we use our Netcetera Identity service. To enable this, a representative from your organization is given Admin rights to Netcetera Identity for this organization. This person is empowered to establish users and permissions within the organization. Find more detailed process information under Netcetera Identity user management.

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.

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

nca-3ds-web-sdk.zipFile size: B

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.
isBrowserSPCAuthenticationSupported	Checks if browser environment supports SPC authentication.
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. This function ensures that a payment request is properly managed by setting a timeout of 60 seconds.

Technical documentation on the Netcetera 3DS Web SDK and examples for usage can be found below.