Google Pay™ 3DS processing for Cryptogram_3DS and PAN_ONLY
Please note, that due to PSD2 regulation, payments need to have SCA (Strong Customer Authentication). This also applies to Google Pay™. Google Pay™ in general is providing 2 types of payload containing payment data. In case of CRYPTOGRAM_3DS payload, payment is already SCA authenticated on the customer device, payload contains proof of authentication and therefore there is no need for addition SCA in form of 3-D Secure. In case of PAN_ONLY payload, payment data are not SCA authenticated. Therefore in order to avoid Soft Declines, 3-D Secure authentication is required. Below guide describes how 3-D Secure 2.0 can be applied for Google Pay payments. This guide can be applied for all Google Pay payments, because will dynamically recognize PAN_ONLY payloads and start the 3-D Secure process. In case of CRYPTOGRAM_3DS payload, 3-D Secure will not be started. A 3-D Secure 2.0 payment sequence may comprise the following distinct activities: 3-D Secure 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 card holder if mandated Authorization Authorize the authenticated transaction with the acquirer
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 will be the same regardless of the underlying 3-D Secure Protocol. In order to start Google Pay™ 3-D Secure payment sequence please post the following key-value-pairs to googlepay.aspx.
Call of interface: general parameters
To carry out a Google Pay payment via a Server-to-Server connection, please use the following URL:
googlepay.aspx |
Request Elements
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>
Netcetera 3DS Web SDK
You may use the operations init3DSMethod or createIframeAndInit3DSMethod at your discreation from the nca3DSWebSDK in order to iniatiate the 3-D Secure Method. Please refer to the Integration Manual at https://mpi.netcetera.com/3dsserver/doc/current/integration.html#Web_Service_API.
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>
Please note that the threeDSMethodNotificationURL as embedded in the Base64 encoded threeDSMethodData value points to 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 .
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>
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>
Please note that the notification URL submited in the challenge request points to and must not be changed.
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
MultiExcerpt named KvpResponse_IntroURL was not found -- Please check the page name and MultiExcerpt name used in the MultiExcerpt-Include macro
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
}
Decrypted Data
Sample decrypted Data
MID=YourMID&PayID=PayIDassignedbyPlatform&TransID=YourTransID