API 3D (beta)

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 Authentification to retrieve required crendetials.

  • 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 that needs to be activated on your account (merchantId).

Step 1: Initial Server-to-Server call

post
Init call

https://api.sandbox.datatrans.com/v1/transactions
Initial Server-to-Server call to retrieve transactionId and submit 3D Secure v1 and v2 parameters.
Request
Response
Request
Headers
Authorization
required
string
Basic MTAwMDAxMTAxMTpYMWVXNmkjJA== see Setup
Content-Type
required
string
API consumes application/json; charset=UTF-8
Body Parameters
amount
required
integer
Transaction in the currency's smallets unit. For example use 1000 for EUR 10.00
currency
required
string
3 letter ISO-4217 character code. For example EUR or USD
refno
required
string
[1..20] characters It should be unique each transaction
paymentMethods
required
array
An array of payment method shortnames Items Enum: "AMX" "DIN" "ECA" "INT" "KLN" "MPW" "MYO" "VIS"
card
required
object
card object must contain following parameters below
number
required
string
Plain text card number or PCI Proxy token
expiryMonth
required
string
Expiry month of card (2 characters)
expiryYear
required
string
Expiry year of card (2 characters)
3D
optional
object
3D object for optional 3D v2 parameters See hint box below for additional information.
option
required
string
option object must contain following parameters below
authenticationOnly
required
boolean
true
redirect
required
object
redirect object must contain following parameters below
successUrl
required
string
Url where cardholder will be redirect in case of successful 3D process
cancelUrl
required
string
Url where cardholder will be redirected in case cancled 3D process
errorUrl
required
string
Url where cardholder will be redirected in case of an error in 3D process
Response
200: OK
If card is 3D enrolled
{
"transactionId": "190527154549809618",
"3D": {
"enrolled": true
}
}
201: Created
If card is not 3D enrolled
{
"transactionId": "190911134600593525",
"3D": {
"enrolled": false
}
}

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 plain text cardnumber
Request with masked token
Response
Request with plain text cardnumber
curl -X POST \
https://api.sandbox.datatrans.com/v1/transactions \
-H 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT,Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT' \
-d '{
"amount": 1000,
"currency": "EUR",
"refno": "NIJ3OSelzyqp",
"paymentMethods": ["ECA"],
"card": {
"number": "5200000000000080",
"cvv": "123",
"expiryMonth": "12",
"expiryYear": "21",
"3D": {
"deviceChannel": "02",
"messageCategory": "01",
"threeDSCompInd": "Y",
"threeDSRequestor": {},
"threeDSServerTransID": "df4b3490-db44-4a88-9619-ab173ff76fbe",
"cardholderAccount": {},
"cardholder": {},
"relaxRegionalValidationRules": false,
"purchase": {},
"acquirer": {},
"merchant": {},
"broadInfo": {},
"deviceRenderOptions": {},
"messageExtension": [],
"browserInformation": {},
"threeRIInd": "02",
"sdkInformation": {}
}
},
"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"
}
}'
Request with masked token
curl -X POST \
https://api.sandbox.datatrans.com/v1/transactions \
-H 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT,Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT' \
-d '{
"amount": 1000,
"currency": "EUR",
"refno": "NIJ3OSelzyqp",
"paymentMethods": ["ECA"],
"card": {
"alias": "520000RIVWAS0080",
"aliasCVV": "YahfrXdEQT67X1u7Og49rg2e",
"expiryMonth": "12",
"expiryYear": "21",
"3D": {
"deviceChannel": "02",
"messageCategory": "01",
"threeDSCompInd": "Y",
"threeDSRequestor": {},
"threeDSServerTransID": "df4b3490-db44-4a88-9619-ab173ff76fbe",
"cardholderAccount": {},
"cardholder": {},
"relaxRegionalValidationRules": false,
"purchase": {},
"acquirer": {},
"merchant": {},
"broadInfo": {},
"deviceRenderOptions": {},
"messageExtension": [],
"browserInformation": {},
"threeRIInd": "02",
"sdkInformation": {}
}
},
"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
Response headers:
Location: https://pay.sandbox.datatrans.com/v1/start/190906151210861442
Response body:
{
"transactionId" : "190906151210861442",
"3D" : {
"enrolled" : true
}
}

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
Status API

https://api.sandbox.datatrans.com/v1/transactions/{transactionId}
Obtain 3D parameters, credit card and cvv token by executing a server to server call with the transactionId received in step 1.
Request
Response
Request
Headers
Authorization
required
string
Basic MTAwMDAxMTAxMTpYMWVXNmkjJA== see setup
Query Parameters
transactionId
required
string
transactionId obtained via /v1/transactions
Response
200: OK
{
"transactionId": "190522141403888597",
"type": "payment",
"status": "authenticated",
"currency": "EUR",
"refno": "NIJ3OSelzyqp",
"paymentMethod": "ECA",
"detail": {
"authorize": {
"amount": 1000
}
},
"history": [
{
"action": "init",
"amount": 1000,
"source": "api",
"date": "2019-05-22T12:14:04.385+00:00",
"success": true,
"ip": "77.109.165.195"
}
],
"card": {
"masked": "520000xxxxxx0080",
"3D": {
"eci": "02",
"xid": "MDAxOTA1MjIxNDE0MDM4ODg1OTc=",
"cavv": "OTkxOTA1MjIxNDE0MjMwMjg2Mjc=",
"threeDSVersion": "1.0.2",
"directoryResponse": "Y",
"authenticationResponse": "Y"
}
}
}

Examples

Request
Response
Request
curl -X GET \
https://api.sandbox.datatrans.com/v1/transactions/190906151210861442 \
-H 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT' \
Response
{
"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"
}
}
}

3-object field name mapping

Datatrans

EMVCo

eci

eci

xid

dsTransId (3Dv2)

xid (3Dv1)

cavvAlgorithm

Only required for 3D Secure 1

cavv

authenticationValue

threeDSVersion

messageVersion

directoryResponse

transStatus (after ARes)

authenticationResponse

transStatus (after RReq)

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.