You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Overview

A 3DS 2.0 payment sequence may comprise the following distinct activities:

  • Versioning
    • Request ACS and DS Protocol Version(s) that correspond to card account range as well as an optional 3DS Method URL

  • 3DS Method

    • Connect the cardholder browser to the issuer ACS to obtain additional browser data

  • Authentication

    • Submit authentication request to the issuer ACS

  • Challenge

    • Challenge the carholder if mandated

  • Authorization

    • Authorize the authenticated transaction with the acquirer


Server-2-Server Sequence Diagram

Server-2-Server Sequence Diagram


Please note that the the communication between client and Access Control Server (ACS) is implemented through iframes. Thus, responses arrive in an HTML subdocument and you may establish correspondent event listeners in your root document.

Alternatively you could solely rely on asynchronous notifications delivered to your backend. In those cases you may have to consider methods such as long polling, SSE or websockets to update the client.

Payment Initiation

The initial request to Computop Paygate will be the same regardless of the underlying 3DS Protocol.



In order to start a server-to-server 3-D Secure card payment sequence please post the following key-value-pairs to https://www.computop-paygate.com/direct.aspx.

Request Elements

Notice: In case of a merchant initiated recurring transaction the JSON objects (besides credentialOnFile and card), the URLNotify and TermURL are not mandatory parameters, because no 3D Secure and no risk evaluation is done by the card issuing bank and the payment result is directly returned within the response.


KeyFormatConditionDescription
1MerchantIDans..30MMerchant identifier assigned by Computop.
2MsgVerans..5M

Message version.

Values accepted:

  • 2.0
3TransIDans..64MTransaction identifier supplied by the merchant. Shall be unique for each payment.
4RefNrans..30OMerchant’s unique reference number, which serves as payout reference in the acquirer EPA file. Please note, without the own shop reference delivery you cannot read out the EPA transaction and regarding the additional Computop settlement file (CTSF) we cannot add the additional payment data.
5schemeReferenceIDans..64C

Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions.

Mandatory: CredentialOnFile – initial false – unschedule MIT / recurring

6Amountn..10MTransaction amount in it smallest unit of the submission currency.
7Currencya3MISO 4217 three-letter currency code.
8cardJSONMCard data.
9Captureans..6

Determines the type and time of payment completion (i.e. dual message systems).

Values accepted:

  • AUTO = completion immediately after authorisation (default value).

  • MANUAL = completion made by the merchant.

  • < Number > = Delay in hours until the completion (whole number; 1 to 696).

10channela..20C

Indicates the type of channel interface being used to initiate the transaction.

Values accepted:

  • Browser

  • App

  • 3RI

If not present the value Browser is implied.

11billingDescriptorans..22OA descriptor to be printed on a cardholder’s statement. Please also refer to the additional comments made elswhere for more information about rules and regulations.
12OrderDescans..768OOrder description.
13TermURL

ans..256

MIn case of 3DS 1.0 fallback: the URL the customer will be returned to at the end of the 3DS 1.0 authentication process.
14AccVerifya3O

Indicator to request an account verification (aka zero value authorization). If an account verification is requested the submitted amount will be optional and ignored for the actual payment transaction (e.g. authorization).

Values accepted:

  • Yes

15

threeDSPolicy

JSON

O

Object specifying authentication policies and excemption handling strategies.

16

threeDSData

JSON

C

Object detailing authentication data in case authentication was performed through a third party or by the merchant.

17

priorAuthenticationInfo

JSON

O

Prior Transaction Authentication Information contains optional information about a 3DS cardholder authentication that occurred prior to the current transaction.

18

browserInfo

JSON

C

Accurate browser information are needed to deliver an optimized user experience. Required for 3DS 2.0 transactions.

19

accountInfo

JSON

O

The account information contains optional information about the customer account with the merchant. Optional for 3DS 2.0 transactions.

20

billToCustomer

JSON

C

The customer that is getting billed for the goods and / or services. Required unless market or regional mandate restricts sending this information.

21

shipToCustomer

JSON

C

The customer that the goods and / or services are sent to. Required (if available and different from billToCustomer) unless market or regional mandate restricts sending this information.

22

billingAddress

JSON

C

Billing address. Required for 3DS 2.0 (if available) unless market or regional mandate restricts sending this information.

23

shippingAddress

JSON

C

Shipping address. If different from billingAddress, required for 3DS 2.0 (if available) unless market or regional mandate restricts sending this information.

24

credentialOnFile

JSON

C

Object specifying type and series of transactions using payment account credentials (e.g. account number or payment token) that is stored by a merchant to process future purchases for a customer. Required if applicable.

25

merchantRiskIndicator

JSON

O

The Merchant Risk Indicator contains optional information about the specific purchase by the customer.

26subMerchantPFJSONOObject specifying SubMerchant (Payment Facilitator) details.
27

URLNotify

an..256

M

The merchant URL that receive asynchrounous reqeusts during the authentication process.

28

UserData

ans..1024

O

If specified at request, Paygate forwards the parameter with the payment result to the shop

29

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

Response Elements


KeyFormatConditionDescription
1

MID

ans..30

M

Merchant identifier assigned by Computop.

2

PayID

ans32

M

Payment/transaction identifier assigned by Computop.

3

XID

ans64

M

ID assigned by Paygate for the operation performed on the payment.

4

TransID

ans..64

M

Transaction identifier supplied by the merchant. Shall be unique for each payment.

5

Code

n8

M

Paygate response code.

6

Status

a..20

M

Status of the transaction.

Values accepted:

  • AUTHENTICATION_REQUEST

  • PENDING

  • FAILED

7

Description

ans..1024

M

Textual description of the code.

8

versioningData

JSON

M

The Card Range Data data element contains information that indicates the most recent EMV 3-D Secure version supported by the ACS that hosts that card range. It also may optionally contain the ACS URL for the 3DS Method if supported by the ACS and the DS Start and End Protocol Versions which support the card range.

9

threeDSLegacy

JSON

M

Object containing the data elements required to construct the Payer Authentication request in case of a fallback to 3DS 1.0.

10

UserData

ans..1024

C

If specified at request, Paygate forwards the parameter with the payment result to the shop


The versioningData object will indicate the EMV 3DS protocol versions (i.e. 2.1.0 or higher) that are supported by Access Control Server of the issuer.


If the corresponding protocol version fields are NULL it means that the BIN range of card issuer is not registered for 3DS 2.0 and a fallback to 3DS 1.0 is required for transactions that are within the scope of PSD2 SCA.


When parsing versioningData please also refer to the subelement errorDetails which will specify the reason if some fields are not pupoluated (e.g. Invalid cardholder account number passed, not available card range data, failure in encoding/serialization of the 3DS Method data etc).


versioningData
{
	"threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c",
	"acsStartProtocolVersion": "2.1.0",
	"acsEndProtocolVersion": "2.1.0",
	"dsStartProtocolVersion": "2.1.0",
	"dsEndProtocolVersion": "2.1.0",
	"threeDSMethodURL": "http://www.acs.com/script",
	"threeDSMethodDataForm": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly93d3cuY29tcHV0b3AtcGF5Z2F0ZS5jb20vY2JUaHJlZURTLmFzcHg_YWN0aW9uPW10aGROdGZuIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxNGRkODQ0Yy1iMGZjLTRkZmUtODYzNS0zNjZmYmY0MzQ2OGMifQ==",
	"threeDSMethodData": {
		"threeDSMethodNotificationURL": "https://www.computop-paygate.com/cbThreeDS.aspx?action=mthdNtfn",
		"threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c"
	}
}

3DS Method

The 3DS Method allows for additional browser information to be gathered by an ACS prior to receipt of the authentication request message (AReq) to help facilitate the transaction risk assessment. Support of 3DS Method is optional and at the discretion of the issuer.


The versioningData object contains a value for threeDSMethodURL . The merchant is supposed to invoke the 3DS Method via a hidden HTML iframe in the cardholder browser and send a form with a field named threeDSMethodData via HTTP POST to the ACS 3DS Method URL.


3DS Method: threeDSMethodURL


Please not that the threeDSMethodURL will be populated by Computop Paygate if the issuer does not support the 3DS Method. The 3DS Method Form Post as outlined below must be performed independently from whether it is supported by the issuer. This is necessary to facilitate direct communication between the browser and Computop Paygate in case of a mandated challenge or a frictionless flow.


3DS Method: No issuer threeDSMethodURL


3DS Method Form Post
<form name="frm" method="POST" action="Rendering URL">
    <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0">
</form>


The ACS will intercat with the Cardholder browser via the HTML iframe and then store the applicable values with the 3DS Server Transaction ID for use when the subsequent authentication message is received containing the same 3DS Server Transaction ID.


Netcetera 3DS Web SDK

You may use the operations init3DSMethod or createIframeAndInit3DSMethod at your discreation from the nca3DSWebSDK in order to iniatiate the 3DS Method. Please refer to the Integration Manual at https://mpi.netcetera.com/3dsserver/doc/current/integration.html#Web_Service_API.


Once the 3DS Method is concluded the ACS will instruct the the cardholder browser through the iFrame response document to submit threeDSMethodData as a hidden form field to the 3DS Method Notification URL.


ACS Response Document
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8"/>
    <title>Identifying...</title>
</head>
<body>
<script>
    var tdsMethodNotificationValue = 'eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9';

    var form = document.createElement("form");
    form.setAttribute("method", "post");
    form.setAttribute("action", "notification URL");

    addParameter(form, "threeDSMethodData", tdsMethodNotificationValue);

    document.body.appendChild(form);
    form.submit();

    function addParameter(form, key, value) {
        var hiddenField = document.createElement("input");
        hiddenField.setAttribute("type", "hidden");
        hiddenField.setAttribute("name", key);
        hiddenField.setAttribute("value", value);
        form.appendChild(hiddenField);
    }
</script>
</body>
</html>



3DS Method Notification Form
<form name="frm" method="POST" action="3DS Method Notification URL">
    <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9">
</form>



Please note that the threeDSMethodNotificationURL as embedded in the Base64 encoded threeDSMethodData value points to Computop Paygate and must not be modified. The merchant notification is delivered to the URLNotify as provided in the original request or as configured for the MerchantID in Computop Paygate.

Authentication

If 3DS Method is supported by the issuer ACS and was invoked by the merchant Computop Paygate will automatically continue with the authentication request once the 3DS Method has completed (i.e. 3DS Method Notification).


The authentication result will be transferred via HTTP POST to the URLNotify . It may indicate that the Cardholder has been authenticated, or that further cardholder interaction (i.e. challenge) is required to complete the authentication.


In case a cardholder challenge is deemed necessary Computop Paygate will transfer a JSON object within the body of HTTP browser response with the elements acsChallengeMandated , challengeRequest , base64EncodedChallengeRequest and acsURL . Otherwise, in a frictionless flow, Computop Paygate will automatically continue and respond to the cardholder browser once the authorization completed.


Cardholder Challenge: Browser Response

Browser Challenge Response

Data Elements


KeyFormatConditionDescription
1

acsChallengeMandated

boolean

M

Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable

2

challengeRequest

object

M

Challenge request object

3

base64EncodedChallengeRequest

string

M

Base64-encoded Challenge Request object

4

acsURL

string

M

Fully qualified URL of the ACS to be used to post the Challenge Request

Schema

Schema: Browser Challenge Response
{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"type": "object",
	"properties": {
		"acsChallengeMandated": {"type": "boolean"},
		"challengeRequest": {"type": "object"},
		"base64EncodedChallengeRequest": {"type": "string"},
		"acsURL": {"type": "string"}
	},
	"required": ["acsChallengeMandated", "challengeRequest", "base64EncodedChallengeRequest", "acsURL"],
	"additionalProperties": false
}

Sample

Sample: Browser Challenge Response
{
	"acsChallengeMandated": true,
	"challengeRequest": {
		"threeDSServerTransID": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
		"acsTransID": "d7c1ee99-9478-44a6-b1f2-391e29c6b340",
		"messageType": "CReq",
		"messageVersion": "2.1.0",
		"challengeWindowSize": "01",
		"messageExtension": [
			{
				"name": "emvcomsgextInChallenge",
				"id": "tc8Qtm465Ln1FX0nZprA",
				"criticalityIndicator": false,
				"data": "messageExtensionDataInChallenge"
			}
		]
	},
	"base64EncodedChallengeRequest": "base64-encoded-challenge-request",
	"acsURL": "acsURL-to-post-challenge-request"
}

Authentication Notification

The data elements of the authentication notification are listed in the table below.


KeyFormatConditionDescription
1

MID

ans..30

M

Merchant identifier assigned by Computop.

2

PayID

ans32

M

Payment/transaction identifier assigned by Computop.

3

TransID

ans..64

M

Transaction identifier supplied by the merchant. Shall be unique for each payment.

4

Code

n8

M

Paygate response code.

5

authenticationResponse

JSON

M

Response object in return of the authentication request with the ACS.

6

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm.

Browser Challenge

If a challenge is deemed necessary (see challengeRequest) the browser challenge will occur within the cardholder browser. To create a challenge it is required to post the value base64EncodedChallengeRequest via an HTML iframe to the ACS URL.


Challenge Request
<form name="challengeRequestForm" method="post" action="acsChallengeURL">
	<input type="hidden" name="creq" value="ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjogIjhhODgwZGMwLWQyZDItNDA2Ny1iY2IxLWIwOGQxNjkwYjI2ZSIsCiAgICAiYWNzVHJhbnNJRCI6ICJkN2MxZWU5OS05NDc4LTQ0YTYtYjFmMi0zOTFlMjljNmIzNDAiLAogICAgIm1lc3NhZ2VUeXBlIjogIkNSZXEiLAogICAgIm1lc3NhZ2VWZXJzaW9uIjogIjIuMS4wIiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjogIjAxIiwKICAgICJtZXNzYWdlRXh0ZW5zaW9uIjogWwoJCXsKCQkJIm5hbWUiOiAiZW12Y29tc2dleHRJbkNoYWxsZW5nZSIsCgkJCSJpZCI6ICJ0YzhRdG00NjVMbjFGWDBuWnByQSIsCgkJCSJjcml0aWNhbGl0eUluZGljYXRvciI6IGZhbHNlLAoJCQkiZGF0YSI6ICJtZXNzYWdlRXh0ZW5zaW9uRGF0YUluQ2hhbGxlbmdlIgoJCX0KICAgIF0KfQ==">
</form>


You may use the operations init3DSChallengeRequest or createIFrameAndInit3DSChallengeRequest from the nca3DSWebSDK in order submit the challenge message through the cardholder browser.


Init 3DS Challenge Request - Example
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <script src="nca-3ds-web-sdk.js" type="text/javascript"></script>
    <title>Init 3DS Challenge Request - Example</title>
</head>
<body>
<!-- This example will show how to initiate Challenge Reqeuests for different window sizes. -->
<div id="frameContainer01"></div>
<div id="frameContainer02"></div>
<div id="frameContainer03"></div>
<div id="frameContainer04"></div>
<div id="frameContainer05"></div>
<iframe id="iframeContainerFull" name="iframeContainerFull" width="100%" height="100%"></iframe>
  
<script type="text/javascript">
    // Load all containers
    iFrameContainerFull = document.getElementById('iframeContainerFull');
    container01 = document.getElementById('frameContainer01');
    container02 = document.getElementById('frameContainer02');
    container03 = document.getElementById('frameContainer03');
    container04 = document.getElementById('frameContainer04');
    container05 = document.getElementById('frameContainer05');
  
  
    // nca3DSWebSDK.init3DSChallengeRequest(acsUrl, creqData, container);
    nca3DSWebSDK.init3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', iFrameContainerFull);
  
    // nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest(acsUrl, creqData, challengeWindowSize, frameName, rootContainer, callbackWhenLoaded);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '01', 'threeDSCReq01', container01);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '02', 'threeDSCReq02', container02);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '03', 'threeDSCReq03', container03);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '04', 'threeDSCReq04', container04);
    nca3DSWebSDK.createIFrameAndInit3DSChallengeRequest('http://example.com', 'base64-encoded-challenge-request', '05', 'threeDSCReq05', container05, () => {
        console.log('Iframe loaded, form created and submitted');
    });
</script>
  
</body>
</html>


Once the cardholder challenge is completed, was cancelled or timed out the ACS will instruct the browser to post the results to the notfication URL as specified in the challenge request and to send a Result Request (RReq) via the Directory Server to the 3DS Server.


Please note that the notification URL submited in the challenge request points to Computop Paygate and must not be changed.

Authorization

After succefull cardholder authentication or proof of attempted authentication/verification is provided Computop Paygate will automatically continue with the payment authorization.


In case the cardholder authentication was not succesfull or proof proof of attempted authentication/verification can not be provided Computop Paygate will not continue with an authorization request.


In both cases Paygate will deliver a final notification to the merchant specified URLNotify with the data elements as listed in the table below.

Payment Notification


KeyFormatConditionDescription
1

MID

ans..30

M

Merchant identifier assigned by Computop.

2

MsgVer

ans..5

M

Message version.

Accepted values:

  • 2.0

3

PayID

ans32

M

Payment/transaction identifier assigned by Computop.

4

XID

an32

M

ID assigned by Paygate for the operation performed on the payment.

5

TransID

ans..64

M

Transaction identifier supplied by the merchant. Shall be unique for each payment.

6

schemeReferenceID

ans..64

C

Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions.

7

TrxTime

an21

M

Transaction time stamp in format DD.MM.YYYY HH:mm:ssff.

8

Status

a..20

M

Status of the transaction.

Values accepted:

  • Authorized

  • OK (Sale)

  • PENDING

  • FAILED

In case of Authentication-only the Status will be either OK or FAILED .

9

Description

ans..1024

M

Textual description of the code.

10

Code

n8

M

Paygate response code.

11

card

JSON

M

Card data.

12

ipInfo

JSON

O

Object containing IP information.

13

threeDSData

JSON

M

Authentication data.

14

resultsResponse

JSON

C

In case the authentication process included a cardholder challenge additional information about the challenge result will be provided.

15

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm.

Browser Payment Response

Additionally the JSON formated data elements as listed below are trasferred in the HTTP response body to the cardholder browser. Please note that the data elements (i.e. MID , Len , Data ) are base64 encoded.

Data Elements


KeyFormatConditionDescription
1

MID

string

M

Merchant identifier assigned by Computop.

2

Len

integer

M

Length of the unencrypted Data string.

3

Data

string

M

Blowfish encrypted string containg a JSON object with MID , PayID and TransID .

Schema

{
	"$schema": "http://json-schema.org/draft-07/schema#",
	"type": "object",
	"properties": {
		"MID": {
			"type": "string"
		},
		"Len": {
			"type": "integer"
		},
		"Data": {
			"type": "string"
		}
	},
	"required": ["MID", "Len", "Data"],
	"additionalProperties": false
}


Merchants are supposed to forward these data elements to their server for decryption and mapping agianst the payment notification. Based on the payment results the merchant server may deliver an appropriate response to the cardholder browser (e.g. success page).

Decrypted Data


KeyFormatConditionDescription
1

MID

ans..30

M

Merchant identifier assigned by Computop.

2

PayID

ans32

M

Payment/transaction identifier assigned by Computop.

3

TransID

ans..64

M

Transaction identifier supplied by the merchant.

Sample decrypted Data 

MID=YourMID&PayID=PayIDassignedbyPaygate&TransID=YourTransID





  • No labels