Sign UpRelease notes
Search…
⌃K
Links

3D Secure API

3D Secure API allows you to perform a standalone 3DS authentication. This makes sense if you're a PCI DSS level 1 merchant or service provider only using our 3DS services or if you want to decouple the card capturing from the authentication process.

Before you start

  1. 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 Enrolment Requirements
3D Secure API requires a 3-D Secure enrolled acquiring contract. Those 3D Secure 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
curl -X POST \
https://api.sandbox.datatrans.com/v1/transactions \
-H 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT' \
-d '{
"amount": 1000,
"currency": "EUR",
"refno": "NIJ3OSelzyqp",
"paymentMethods": ["ECA"],
"card": {
"alias": "AAABcHxr-sDssdexyrAAAfyXWIgaAF40",
"expiryMonth": "06",
"expiryYear": "25",
"3D": {
"acquirer": {
"acquirerMerchantId": "1354656",
"acquirerBin": "9854128"
},
"merchant": {
"mcc": "4722",
"merchantName": "Example Travel Ltd."
}
}
},
"option": {
"authenticationOnly": true
},
"redirect": {
"successUrl": "https://pay.sandbox.datatrans.com/upp/merchant/successPage.jsp",
"cancelUrl": "https://pay.sandbox.datatrans.com/upp/merchant/cancelPage.jsp",
"errorUrl": "https://pay.sandbox.datatrans.com/upp/merchant/errorPage.jsp"
}
}'
curl -X POST \
https://api.sandbox.datatrans.com/v1/transactions \
-H 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT' \
-d '{
"amount": 1000,
"currency": "EUR",
"refno": "NIJ3OSelzyqp",
"paymentMethods": ["ECA"],
"card": {
"number": "5200000000000080",
"cvv": "123",
"expiryMonth": "12",
"expiryYear": "21",
"3D": {
"acquirer": {
"acquirerMerchantId": "1234567",
"acquirerBin": "9876543"
},
"merchant": {
"mcc": "4722",
"merchantName": "Example Travel Ltd."
}
}
},
"option": {
"authenticationOnly": true
},
"redirect": {
"successUrl": "https://pay.sandbox.datatrans.com/upp/merchant/successPage.jsp",
"cancelUrl": "https://pay.sandbox.datatrans.com/upp/merchant/cancelPage.jsp",
"errorUrl": "https://pay.sandbox.datatrans.com/upp/merchant/errorPage.jsp"
}
}'
Response headers:
Location: https://pay.sandbox.datatrans.com/v1/start/190906151210861442
​
Response body:
{
"transactionId" : "190906151210861442",
"3D" : {
"enrolled" : true
}
}
To send additional 3D parameters, please check the card.3D object here: https://api-reference.datatrans.ch/#operation/init​
If the initialization failed, you will receive one of the of the following error codes.
"UNKNOWN_ERROR", "UNAUTHORIZED", "INVALID_JSON_PAYLOAD", "UNRECOGNIZED_PROPERTY", "INVALID_PROPERTY", "CLIENT_ERROR", "SERVER_ERROR", "INVALID_TRANSACTION_STATUS", "TRANSACTION_NOT_FOUND", "EXPIRED_CARD", "INVALID_CARD", "BLOCKED_CARD", "UNSUPPORTED_CARD", "INVALID_ALIAS", "INVALID_CVV", "DUPLICATE_REFNO", "DECLINED", "SOFT_DECLINED", "INVALID_SIGN", "BLOCKED_BY_VELOCITY_CHECKER", "THIRD_PARTY_ERROR", "REFERRAL", "INVALID_SETUP".
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 cardholder 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
curl -X GET \
https://api.sandbox.datatrans.com/v1/transactions/190906151210861442 \
-H 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT' \
​
{
"transactionId": "190906151210861442",
"type": "payment",
"status": "authenticated",
"currency": "EUR",
"refno": "EVO-1564475113071",
"paymentMethod": "ECA",
"detail": {
"authorize": {
"amount": 1000
}
},
"history": [
{
"action": "init",
"amount": 1000,
"source": "api",
"date": "2019-09-06T13:12:11.915+00:00",
"success": true,
"ip": "77.109.165.195"
},
{
"action": "authenticate",
"amount": 1000,
"source": "web",
"date": "2019-09-06T13:12:21.915+00:00",
"success": true,
"ip": "77.109.165.195"
}
],
"card": {
"masked": "520000xxxxxx0080",
"expiryMonth": "12",
"expiryYear": "21",
"info": {
"brand": "MCI CREDIT",
"type": "credit",
"usage": "consumer",
"country": "MY",
"issuer": "DATATRANS"
},
"3D": {
"eci": "02",
"xid": "MDAxOTA5MDYxNTEyMTA4NjE0NDI=",
"cavv": "OTkxOTA5MDYxNTEyMjE3NTE0NjA=",
"threeDSVersion": "1.0.2",
"cavvAlgorithm": "1",
"directoryResponse": "Y",
"authenticationResponse": "Y",
"cardHolderInfo": "Detailed issuer notification if available",
"threeDSTransactionId": "8558c931-277b-4240-adfc-443cbd61a2c0"
}
}
}

​

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
​transStatus
(after ARes)
Transaction status after ARes
authenticationResponse
​transStatus ​
(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
Not authenticated, but 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
Not authenticated, but 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 Secure 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.
AUTHENTICATE - Previous
Overview
Next - AUTHENTICATE
3D Secure Fields (JS)
Last modified 2mo ago