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.
OAuth Client Credentials Grant
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:
Finally, the request should look like:- "grant_type": "client_credentials" - 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:
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.
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. |
| 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.
Netcetera 3DS Web SDK Technical documentation
Init 3DS Method Request - Example
Init 3DS Challenge Request - Example