Card processing - Server-2-Server integration

Payment Initiation

Call of interface: general parameters

Notice: For credit card payments with 3-D Secure, please note the different cases as explained separately in the chapter at the start of the handbook. If the credit card is registered for Verified or SecureCode or SafeKey, the next phase is divided into two steps of authentication and payment. However it always begins in the same way via the direct.aspx interface. The first response however is the receipt of Javascript code or other parameters in order to carry out a second call up of the direct3d.aspx interface. Only after that, do you receive the listed parameter as a response.

To carry out a credit card payment via a Server-to-Server connection, please use the following URL:

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 3-D Secure and no risk evaluation is done by the card issuing bank and the payment result is directly returned within the response.

General parameters for credit card payments via socket connection

Please note the additional parameter for a specific credit card integration in the section "Specific parameters"

Response Elements (authentication)

versioningData

The versioningData object will indicate the EMV 3-D Secure 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 3-D Secure 2.0 and a fallback to 3-D Secure 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 3-D Secure Method data etc).

BASEURL=

{
	"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": "BASEURL/cbThreeDS.aspx?action=mthdNtfn",
		"threeDSServerTransID": "14dd844c-b0fc-4dfe-8635-366fbf43468c"
	}
}

3-D Secure Method

The 3-D Secure 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 3-D Secure 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 3-D Secure 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 3-D Secure Method URL.

3-D Secure Method: threeDSMethodURL

Please note that the threeDSMethodURL will be populated by  if the issuer does not support the 3-D Secure Method. The 3-D Secure 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  in case of a mandated challenge or a frictionless flow.

3-D Secure Method: No issuer threeDSMethodURL

3-D Secure Method Form Post

<form name="frm" method="POST" action="Rendering URL">
    <input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIn0">
</form>

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

Once the 3-D Secure Method is concluded the ACS will instruct the cardholder browser through the iFrame response document to submit threeDSMethodData as a hidden form field to the 3-D Secure 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>

3-D Secure Method Notification Form

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

Authentication

If 3-D Secure Method is supported by the issuer ACS and was invoked by the merchant  will automatically continue with the authentication request once the 3-D Secure Method has completed (i.e. 3-D Secure 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  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,  will automatically continue and respond to the cardholder browser once the authorization completed.

Cardholder Challenge: Browser Response

Browser Challenge Response

Data Elements

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: Browser Challenge Response

{
	"acsChallengeMandated": false,
	"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.

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 3-D Secure 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 3-D Secure 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 3-D Secure Server.

Authorization

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

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

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

Payment Notification

Browser Payment Response

Additionally the JSON formatted data elements as listed below are transferred 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

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

Sample decrypted Data

MID=YourMID&PayID=PayIDassignedbyPlatform&TransID=YourTransID