Overview
A 3DS 3DS 3DS carholderwidth | 900px |
---|
Payment Initiation
The initial request to Computop PaygatePayment Initiation
Multiexcerpt | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
The initial request to |
3-D Secure Protocol.
In order to start a server-to-server 3-D Secure card payment sequence please post the following key-value-pairs to |
|
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
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Request_Intro PageWithExcerpt Reuse API
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.
Table Filter | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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)
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName RestResponse_IntroURL PageWithExcerpt Reuse API
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Response_Intro PageWithExcerpt Reuse API
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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=
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName BaseURL PageWithExcerpt Wording
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
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
Multiexcerpt | ||||
---|---|---|---|---|
| ||||
|
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 Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt Wording
in case of a mandated challenge or a frictionless flow. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt Wording
3-D Secure Method: No issuer threeDSMethodURL
Multiexcerpt | ||||
---|---|---|---|---|
| ||||
|
3-D Secure Method Form Post
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
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.
Info | ||
---|---|---|
| ||
You may use the operations |
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
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
3-D Secure Method Notification Form
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Note | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Please note that the |
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). Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt Wording
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 Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt Wording acsChallengeMandated
, challengeRequest
, base64EncodedChallengeRequest
and acsURL
. Otherwise, in a frictionless flow,
will automatically continue and respond to the cardholder browser once the authorization completed. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt Wording
Cardholder Challenge: Browser Response
Multiexcerpt | ||||
---|---|---|---|---|
| ||||
|
Browser Challenge Response
Data Elements
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Schema: Browser Challenge Response
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Sample: Browser Challenge Response
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Authentication Notification
The data elements of the authentication notification are listed in the table below.
Table Filter | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
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
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
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.
Note | ||||||||
---|---|---|---|---|---|---|---|---|
Please note that the notification URL submited in the challenge request points to |
Authorization
After successful cardholder authentication or proof of attempted authentication/verification is provided
will automatically continue with the payment authorization. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt Wording
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. Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Name PageWithExcerpt Wording
In both cases
will deliver a notification with the authentication result to the merchant specified Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName Platform-Kurz PageWithExcerpt Wording URLNotify
with the data elements as listed in the table below.
Payment Notification
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName RestResponse_IntroURL PageWithExcerpt Reuse API
Multiexcerpt include SpaceWithExcerpt EN MultiExcerptName KvpResponse_IntroURL PageWithExcerpt Reuse API
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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
Table Filter | |||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Schema
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
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
Table Filter | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Sample decrypted Data
Multiexcerpt | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Message version.
Values accepted:
-
2.0
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).
Indicates the type of channel interface being used to initiate the transaction.
Values accepted:
Browser
If not present the value Browser
is implied.
ans..256
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
JSON
O
Object specifying authentication policies and excemption handling strategies.
JSON
C
Object detailing authentication data in case authentication was performed through a third party or by the merchant.
JSON
O
Prior Transaction Authentication Information contains optional information about a 3DS cardholder authentication that occurred prior to the current transaction.
JSON
C
Accurate browser information are needed to deliver an optimized user experience. Required for 3DS 2.0 transactions.
JSON
O
The account information contains optional information about the customer account with the merchant. Optional for 3DS 2.0 transactions.
JSON
C
The customer that is getting billed for the goods and / or services. Required unless market or regional mandate restricts sending this information.
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.
JSON
C
Billing address. Required for 3DS 2.0 (if available) unless market or regional mandate restricts sending this information.
JSON
C
Shipping address. If different from billingAddress, required for 3DS 2.0 (if available) unless market or regional mandate restricts sending this information.
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.
JSON
O
The Merchant Risk Indicator contains optional information about the specific purchase by the customer.
URLNotify
an..256
M
The merchant URL that receive asynchrounous reqeusts during the authentication process.
ans..1024
O
If specified at request, Paygate forwards the parameter with the payment result to the shop
an64
M
Hash Message Authentication Code (HMAC) with SHA-256 algorithm
Response Elements
ans..30
M
Merchant identifier assigned by Computop.
ans32
M
Payment/transaction identifier assigned by Computop.
ans64
M
ID assigned by Paygate for the operation performed on the payment.
ans..64
M
Transaction identifier supplied by the merchant. Shall be unique for each payment.
n8
M
Paygate response code.
Status
a..20
M
Status of the transaction.
Values accepted:
AUTHENTICATION_REQUEST
-
PENDING
FAILED
Description
ans..1024
M
Textual description of the code.
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.
JSON
M
Object containing the data elements required to construct the Payer Authentication request in case of a fallback to 3DS 1.0.
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).
Code Block | ||||
---|---|---|---|---|
| ||||
{
"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.
threeDSMethodURL
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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.
title | Netcetera 3DS Web SDK |
---|
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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<!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> |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<form name="frm" method="POST" action="3DS Method Notification URL">
<input type="hidden" name="threeDSMethodData" value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImUxYzFlYmViLTc0ZTgtNDNiMi1iMzg1LTJlNjdkMWFhY2ZhMiJ9">
</form> |
Note |
---|
Please note that the |
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
acsChallengeMandated
boolean
M
Indication of whether a challenge is required for the transaction to be authorised due to local/regional mandates or other variable
object
M
Challenge request object
base64EncodedChallengeRequest
string
M
Base64-encoded Challenge Request object
acsURL
string
M
Fully qualified URL of the ACS to be used to post the Challenge Request
Schema
Code Block | ||||
---|---|---|---|---|
| ||||
{
"$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
Code Block | ||||
---|---|---|---|---|
| ||||
{
"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.
MID
ans..30
M
Merchant identifier assigned by Computop.
PayID
ans32
M
Payment/transaction identifier assigned by Computop.
TransID
ans..64
M
Transaction identifier supplied by the merchant. Shall be unique for each payment.
Code
n8
M
Paygate response code.
JSON
M
Response object in return of the authentication request with the ACS.
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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<!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.
Note |
---|
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
MID
ans..30
M
Merchant identifier assigned by Computop.
ans..5
M
Message version.
Accepted values:
2.0
PayID
ans32
M
Payment/transaction identifier assigned by Computop.
XID
an32
M
ID assigned by Paygate for the operation performed on the payment.
TransID
ans..64
M
Transaction identifier supplied by the merchant. Shall be unique for each payment.
schemeReferenceID
ans..64
C
Card scheme specific transaction ID required for subsequent credential-on-file payments, delayed authorizations and resubmssions.
TrxTime
an21
M
Transaction time stamp in format DD.MM.YYYY HH:mm:ssff.
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
.
Description
ans..1024
M
Textual description of the code.
Code
n8
M
Paygate response code.
JSON
M
Card data.
JSON
O
Object containing IP information.
JSON
M
Authentication data.
JSON
C
In case the authentication process included a cardholder challenge additional information about the challenge result will be provided.
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
MID
string
M
Merchant identifier assigned by Computop.
Len
integer
M
Length of the unencrypted Data
string.
Data
string
M
Blowfish encrypted string containg a JSON object with MID
, PayID
and TransID
.
Schema
Code Block | ||
---|---|---|
| ||
{
"$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
MID
ans..30
M
Merchant identifier assigned by Computop.
PayID
ans32
M
Payment/transaction identifier assigned by Computop.
TransID
ans..64
M
Transaction identifier supplied by the merchant.
Sample decrypted Data
Code Block | ||
---|---|---|
| ||
MID=YourMID&PayID=PayIDassignedbyPaygate&TransID=YourTransID |