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:

OperationRequestResponseDescription
versioningThreeDSServerVersioningRequestThreeDSServerVersioningResponseInvoke 3DS Method Versioning
authenticationThreeDSServerAuthenticationRequestThreeDSServerAuthenticationResponseInitiate authentication
challenge-responseThreeDSServerFinalCResRequestThreeDSServerChallengeResponseDecode, validate and return challenge response
challenge-cancelledChallenge Cancelled Requestempty responseNotify 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:

OperationRequestDescription
resultsresultsSend 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:

OperationQuery ParametersResponseDescription
card-ranges-supported -protocol-versionspage (int, required), size (int, required), schemeId (String, optional)PagePResCardRangeDataEntryAll 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:

OperationRequestResponseDescription
createPaReqIfEnrolledPaReqCreationRequestPaReqCreationResponseVerifies enrollment with the Directory Server and creates the PaReq to be sent to the ACS.
validatePaResPaResValidationRequestPaResValidationResponseValidates 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-urlencoded
  • application/xml
  • application/json

While they can produce the following media types:

  • application/xml
  • application/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:

OperationRequestResponseDescription
createAuthenticationReqAuthReqCreationRequestAuthReqCreationResponseCreates the MsgReq to be sent to UPOP.
validateAuthenticationResAuthResValidationRequestAuthResValidationResponseValidates the MsgRes returned by UPOP and provides authentication information.
inquireAuthenticationStatusAuthStatusInquiryRequestAuthStatusInquiryResponseInquires UPOP about the status of a transaction

Media Types

The web service operations can consume the following media types:

  • application/x-www-form-urlencoded
  • application/xml
  • application/json

While they can produce the following media types:

  • application/xml
  • application/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:

OperationDescription
init3DSMethodCreates an HTML structure and attaches a form with a single input (threeDSMethodData) and automatically submits it to the threeDSMethodUrl.
createIframeAndInit3DSMethodCreates 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.
init3DSChallengeRequestCreates an HTML structure and attaches a form with a single input (creq) and automatically submits it to the acsUrl.
createIFrameAndInit3DSChallengeRequestCreates 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.
isBrowserSPCAuthenticationSupportedChecks if browser environment supports SPC authentication.
initiateSPCAuthenticationInitiates 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