SecureFields 3D
Use Secure Fields integration for Tokenisation and Authentication only in your frontend.

Before you start

    1.
    ****Sign up for a free PCI Proxy sandbox account.
    This service requires basic authentication. Please refer to Authentication to retrieve required credentials.
    Make sure to use our 3D Secure enabled test credit cards here.
3D Secure Enrollment Requirements
Secure Fields 3D requires a 3D Secure enrolled acquiring contract for each card brand. Those 3D acquiring data needs to be sent in the initial call to /v1/transactions/secureFields

Step 1: Initial Server-to-Server call

post
https://api.sandbox.datatrans.com
/v1/transactions/secureFields
Init call
3D Secure 2 allows you send additional, optional data to ensure increased acceptance and frictionless rate at the issuer. Please refer to the official EMVCo 3D specification 2.1.0 for parameter requirements sent in the card brands object. https://www.emvco.com/emv-technologies/3d-secure/ or contact us for more information.

Example

Request
Response
1
curl -L -X POST 'https://api.sandbox.datatrans.com/v1/transactions/secureFields' \
2
-H 'Authorization: Basic MTEwMDAxNzc4OTpNQUd6UUVEbkVxd001d0Vr' \
3
-H 'Content-Type: application/json' \
4
-d '{
5
"amount" : 1000,
6
"currency" : "EUR",
7
"returnUrl": "https://pay.sandbox.datatrans.com/upp/merchant/successPage.jsp",
8
"VIS": {
9
"3D": {
10
"acquirer": {
11
"acquirerBin": "658942",
12
"acquirerMerchantId": "XCGHPB1U0ZIK459"
13
},
14
"merchant": {
15
"mcc": "4722",
16
"merchantName": "Test-OTA"
17
}
18
}
19
},
20
"ECA": {
21
"3D": {
22
"acquirer": {
23
"acquirerBin": "357941",
24
"acquirerMerchantId": "XLKDPB1U0ZIK658"
25
},
26
"merchant": {
27
"mcc": "4722",
28
"merchantName": "Test-OTA"
29
}
30
}
31
},
32
"AMX": {
33
"3D": {
34
"acquirer": {
35
"acquirerBin": "",
36
"acquirerMerchantId": "9999999999"
37
},
38
"merchant": {
39
"mcc": "4722",
40
"merchantName": "Test-OTA"
41
}
42
}
43
}
44
}'
Copied!
1
{
2
"transactionId" : "190510170631533875"
3
}
Copied!
If the initial server to server call failed, you will receive one of these error codes.
To use the Authentication only API you need to get the following information from your acquirer as they are part of the 3D Secure 2 enrolment process between your acquirer and card schemes.
Name
Description
acquirerMerchantId
Acquirer Merchant ID - Acquirer-assigned Merchant identifier.
This may be the same value that is used in authorisation requests sent on behalf of the 3DS Requestor and is represented in ISO 8583 formatting requirements.
Length: Variable, maximum 35 characters
acquirerBin
Acquirer BIN - Acquiring institution identification code as assigned by the DS receiving the AReq message.
Length: Variable, maximum 11 characters.
mcc
Merchant Category Code - DS-specific code describing the Merchant’s type of business, product or service. The four-digit MCC registered with the schemes for the same acquirerMerchantID sent in the request.
Length: 4 characters
merchantName
Merchant Name - Merchant name assigned by the Acquirer or Payment System; it is the merchant name that the issuer presents to the cardholder if they get a challenge.
Length: Variable, maximum 40 characters
Above mentioned data are only required for Visa and Mastercard. If you need to authenticate AMEX as well please contact us.

Step 2: Setup SecureFields

To get started include the following script on your page.
SecureFields Script
Minified version
1
<script src="https://pay.sandbox.datatrans.com/upp/payment/js/secure-fields-2.0.0.js"></script>
Copied!
1
<script src="https://pay.sandbox.datatrans.com/upp/payment/js/secure-fields-2.0.0.min.js"></script>
Copied!
Please make sure to always load it directly from https://pay.sandbox.datatrans.com

Step 3: Create payment form

In order for Secure Fields to insert the card number and CVV iframes at the right place, create empty DOM elements and assign them unique IDs. In the example below those are:
    card-number-placeholder
    cvv-placeholder
1
<form>
2
<div>
3
<div>
4
<label for="card-number-placeholder">Card Number</label>
5
<!-- card number container -->
6
<div id="card-number-placeholder" style="width: 250px;"></div>
7
</div>
8
<div>
9
<label for="cvv-placeholder">Cvv</label>
10
<!-- cvv container -->
11
<div id="cvv-placeholder" style="width: 90px;"></div>
12
</div>
13
14
<button type="button" id="go">Get Token!</button>
15
</div>
16
</form>
Copied!

Step 4: Initialize Secure Fields with the transactionId

Start with creating a new Secure Fields instance:
1
var secureFields = new SecureFields();
2
3
// Multiple instances might be created and used independently:
4
// e.g. var secureFields2 = new SecureFields();
Copied!
Initialize it with your transactionId and specify which DOM element containers should be used to inject the iframes:
1
secureFields.init(
2
'190520110934541218',
3
{
4
cardNumber: {
5
placeholderElementId: 'card-number-placeholder',
6
inputType: 'tel'
7
},
8
cvv: {
9
placeholderElementId: 'cvv-placeholder',
10
inputType: 'tel'
11
}
12
},
13
{
14
debug: true
15
}
16
);
Copied!
Afterwards add parameter expm and expy , submit the form and listen for the success event:
1
$(function() {
2
$("#go").click( function() {
3
secureFields.submit({ // submit the "form"
4
expm: 12,
5
expy: 21
6
});
7
});
8
});
9
10
secureFields.on("success", function(data) {
11
if(data.transactionId) {
12
// transmit data.transactionId and the rest
13
// of the form to your server.
14
// redirect the customers browser to the URL
15
// within data.redirect. See Step 5.
16
}
17
});
Copied!

Step 5: Display a 3D secure challenge

The success event returns a redirect attribute which contains the 3D URL if a challenge is required. Redirect the card holder to this URL to trigger the 3D authentication process.
Once the card holder completed the 3D process, the browser will be redirected to the returnUrl passed to the /v1/transactions/secureFields API, with a POST request containing the variables upptransactionId and status_3d .

Step 6: Obtain 3D parameters and tokens

get
https://api.sandbox.datatrans.com
/v1/transactions/{transactionId}
Status API

Examples

Request
Response
1
curl -u 1100018081:2fgVhQOYZK0io9ct https://api.sandbox.datatrans.com/v1/transactions/190510164649321735
Copied!
1
{
2
"transactionId": "190520111958152753",
3
"type": "payment",
4
"status": "authenticated",
5
"currency": "EUR",
6
"refno": "N/A",
7
"paymentMethod": "ECA",
8
"detail": {
9
"authorize": {
10
"amount": 1000
11
}
12
},
13
"card": {
14
"alias": "AAABcHxr-sDssdexyrAAAfyXWIgaAF40",
15
"fingerprint": "F-dV5V8dE0SZLoTurWbq2HZp",
16
"masked": "520000xxxxxx0080",
17
"aliasCVV":"WWguOT-vQKybTMo1CALTjjwZ",
18
"expiryMonth": "12",
19
"expiryYear": "21",
20
"info": {
21
"brand": "MASTERCARD",
22
"type": "credit",
23
"usage": "consumer",
24
"country": "RO",
25
"issuer": "DATATRANS"
26
},
27
"3D": {
28
"eci": "02",
29
"xid": "1f88043a-7d5c-431b-be5d-bfebd6088992",
30
"cavv": "OTkxOTA4MDkxNjMzMTYwNTUwMzY=",
31
"threeDSVersion": "2.1.0",
32
"directoryResponse": "Y",
33
"authenticationResponse": "Y",
34
"transStatusReason": "01",
35
"cardHolderInfo": "Detailed issuer notification if available",
36
"threeDSTransactionId": "8558c931-277b-4240-adfc-443cbd61a2c0"
37
}
38
}
39
}
Copied!

3D object field name mapping

Datatrans
EMVCo
Description
eci
eci
The Electronic Commerce Indicator
xid
dsTransId (3Dv2)
xid (3Dv1)
The transaction ID returned by the directory server
cavvAlgorithm
Only required for 3D Secure 1
The 3D algorithm
cavv
The Cardholder Authentication Verification Value
threeDSVersion
The 3D version
directoryResponse
(after ARes)
Transaction status after ARes
authenticationResponse
(after RReq)
Transaction status after RReq
threeDSTransactionId
Universally unique transaction identifier.
cardHolderInfo
Optional message provided by the ACS/Issuer to the Cardholder
transStatusReason
Provides additional information on the failed 3D authentication

Directory response & authentication response

We return the directory response for any transaction where a 3D Secure verification can take place and the authentication response for any transaction where a 3D Secure challenge flow was completed. In other words: directoryResponse tells you if a card is enrolled or needs authentication and authenticationResponse returns the challenge flow response.

Directory Response (Transaction status after ARes)

Value
3Dv2
Description
Y
authenticated
The card or account was authenticated seamlessly with 3D Secure. No challenge flow will take place.
N
authentication failed
Not authenticated
U
not available
The authentication or account verification could not be performed. This is usually linked to technical problems.
C
challenge needed
Further cardholder interaction is required to complete the authentication.
R
rejected
Not authenticated because the issuer is rejecting authentication.
A
authentication attempt
A proof of authentication attempt was generated. One or more 3D Secure authentication attempts were performed but no authentication or account verification was completed successfully. This serves as a proof that 3D Secure authentication was attempted and may also be returned if a cardholder skips the 3D Secure registration.

Authentication Response (Transaction status after RReq (Challenge flow))

Value
3Dv2
Description
Y
authenticated
The authentication was successful.
N
authentication failed
The authentication or account could not be verified. This will be returned when the authentication fails.
U
not available
The authentication or account verification could not be performed. This is usually linked to technical problems.
A
authentication attempt
A proof of authentication attempt was generated. One or more 3D Secure authentication attempts were performed but no authentication or account verification was completed successfully. This serves as a proof that 3D Secure authentication was attempted and may also be returned if a cardholder skips the 3D Secure registration.
C
process incomplete
Further cardholder interaction is required to complete the authentication.

Step 7: Forward 3D data

The received "3D" object contains parameters with the result of the 3D-Secure process and can be forwarded to 3rd party payment gateway. If you decide to use Datatrans payment gateway please continue with our Authorize API.

Examples

Find a working sample here (change the transactionId all the time): https://github.com/datatrans/secure-fields-sample/blob/secure-fields-init-with-transactionId/index.html
Last modified 4d ago