API 3D
Use server-to-server based Authentication only integration to receive 3D authentication data.

Before you start

    1.
    ****Sign up for a free PCI Proxy sandbox account.
    This service requires basic authentication. Please refer to Authentication to retrieve the 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. Those 3D acquiring data has to be sent dynamically in the initial request to /v1/transactions

Step 1: Initial Server-to-Server call

post
https://api.sandbox.datatrans.com
/v1/transactions
Init call
Refer to the official EMVCo 3D specification 2.1.0 for parameter requirements sent in the 3Dobject. https://www.emvco.com/emv-technologies/3d-secure/

Examples

Request with token
Request with plain text cardnumber
Response
1
curl -X POST \
2
https://api.sandbox.datatrans.com/v1/transactions \
3
-H 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT,Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT' \
4
-d '{
5
"amount": 1000,
6
"currency": "EUR",
7
"refno": "NIJ3OSelzyqp",
8
"paymentMethods": ["ECA"],
9
"card": {
10
"alias": "AAABcHxr-sDssdexyrAAAfyXWIgaAF40",
11
"expiryMonth": "12",
12
"expiryYear": "21",
13
"3D": {
14
"acquirer": {
15
"acquirerMerchantId": "1354656",
16
"acquirerBin": "9854128"
17
},
18
"merchant": {
19
"mcc": "4722",
20
"merchantName": "Example Travel Ltd."
21
}
22
}
23
},
24
"option": {
25
"authenticationOnly": true
26
},
27
"redirect": {
28
"successUrl": "https://pay.sandbox.datatrans.com/upp/merchant/successPage.jsp",
29
"cancelUrl": "https://pay.sandbox.datatrans.com/upp/merchant/cancelPage.jsp",
30
"errorUrl": "https://pay.sandbox.datatrans.com/upp/merchant/errorPage.jsp"
31
}
32
}'
Copied!
1
curl -X POST \
2
https://api.sandbox.datatrans.com/v1/transactions \
3
-H 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT' \
4
-d '{
5
"amount": 1000,
6
"currency": "EUR",
7
"refno": "NIJ3OSelzyqp",
8
"paymentMethods": ["ECA"],
9
"card": {
10
"number": "5200000000000080",
11
"cvv": "123",
12
"expiryMonth": "12",
13
"expiryYear": "21",
14
"3D": {
15
"acquirer": {
16
"acquirerMerchantId": "1234567",
17
"acquirerBin": "9876543"
18
},
19
"merchant": {
20
"mcc": "4722",
21
"merchantName": "Example Travel Ltd."
22
}
23
}
24
},
25
"option": {
26
"authenticationOnly": true
27
},
28
"redirect": {
29
"successUrl": "https://pay.sandbox.datatrans.com/upp/merchant/successPage.jsp",
30
"cancelUrl": "https://pay.sandbox.datatrans.com/upp/merchant/cancelPage.jsp",
31
"errorUrl": "https://pay.sandbox.datatrans.com/upp/merchant/errorPage.jsp"
32
}
33
}'
Copied!
1
Response headers:
2
Location: https://pay.sandbox.datatrans.com/v1/start/190906151210861442
3
4
Response body:
5
{
6
"transactionId" : "190906151210861442",
7
"3D" : {
8
"enrolled" : true
9
}
10
}
Copied!
To send additional 3D parameters, please check the card.3D object here: https://api-reference.datatrans.ch/#operation/init
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
acquirerBin
Acquirer BIN
Acquiring institution identification code
mcc
Merchant Category Code
Describes the Merchant’s type of business, product or service.
merchantName
Merchant Name
Name which will be displayed on the ACS page.

Step 2: Display a 3D secure challenge

In the body of the response you receive the transactionID and in the location header the 3D-redirectURL. Redirect the cardholder to this URL to trigger the 3D-Secure process. Once the card holder completed the 3D-Secure process, he will be redirected to the successUrl passed to the v1/transactions API.

Step 3: Obtain 3D parameters

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

Examples

Request
Response
1
curl -X GET \
2
https://api.sandbox.datatrans.com/v1/transactions/190906151210861442 \
3
-H 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT' \
Copied!
1
{
2
"transactionId": "190906151210861442",
3
"type": "payment",
4
"status": "authenticated",
5
"currency": "EUR",
6
"refno": "EVO-1564475113071",
7
"paymentMethod": "ECA",
8
"detail": {
9
"authorize": {
10
"amount": 1000
11
}
12
},
13
"history": [
14
{
15
"action": "init",
16
"amount": 1000,
17
"source": "api",
18
"date": "2019-09-06T13:12:11.915+00:00",
19
"success": true,
20
"ip": "77.109.165.195"
21
},
22
{
23
"action": "authenticate",
24
"amount": 1000,
25
"source": "web",
26
"date": "2019-09-06T13:12:21.915+00:00",
27
"success": true,
28
"ip": "77.109.165.195"
29
}
30
],
31
"card": {
32
"masked": "520000xxxxxx0080",
33
"expiryMonth": "12",
34
"expiryYear": "21",
35
"info": {
36
"brand": "MCI CREDIT",
37
"type": "credit",
38
"usage": "consumer",
39
"country": "MY",
40
"issuer": "DATATRANS"
41
},
42
"3D": {
43
"eci": "02",
44
"xid": "MDAxOTA5MDYxNTEyMTA4NjE0NDI=",
45
"cavv": "OTkxOTA5MDYxNTEyMjE3NTE0NjA=",
46
"threeDSVersion": "1.0.2",
47
"cavvAlgorithm": "1",
48
"directoryResponse": "Y",
49
"authenticationResponse": "Y",
50
"cardHolderInfo": "Detailed issuer notification if available",
51
"threeDSTransactionId": "8558c931-277b-4240-adfc-443cbd61a2c0"
52
}
53
}
54
}
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. The authentication process is incomplete.

Step 4: 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 gateways. If you decide to use Datatrans payment gateway please continue with our Authorize API.
Last modified 4d ago