3DS Server Integration Manual
3DS Server Web Service API
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 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 |
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 | results | 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), schemeId (String, optional) | PagePResCardRangeDataEntry | All available card ranges and supported protocol versions. If schemeId is not sent, card ranges for all schemes are returned. |
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 UPOP API documentation for details about the request / response structures and for sample requests.
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 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