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
Init call

https://api.sandbox.datatrans.com/v1/transactions
Initial Server-to-Server call to retrieve transactionId and submit 3D Secure 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 smallest 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 with one element: payment method shortname "AMX" "CUP" "ECA" "DIN" "DIS" "JCB" "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
required
object
3D object for the 3D v2 parameters See the hint box below for additional information.
option
required
string
option object must contain the 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 of canceled 3D process
errorUrl
required
string
Url where cardholder will be redirected in case of an error in 3D process
Response
201: Created
Returns the transactionId and wheter the card is enrolled for 3D or not.
{
"transactionId": "190527154549809618",
"3D": {
"enrolled": true
}
},
{
"transactionId": "190911134600593525",
"3D": {
"enrolled": false
}
}
400: Bad Request
Invalid Request: Returns error object with an error code and an error message.
{
"error": {
"code": "INVALID_PROPERTY",
"message": "init.refno must not be null"
}
}

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
Request with 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": "AAABcHxr-sDssdexyrAAAfyXWIgaAF40",
"expiryMonth": "12",
"expiryYear": "21",
"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"
}
}'
Request with plain text cardnumber
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
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 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
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",
"cardHolderInfo": "Detailed issuer notification if available",
"threeDSTransactionId": "8558c931-277b-4240-adfc-443cbd61a2c0"
}
}
}

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",
"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

authenticationValue

The Cardholder Authentication Verification Value

threeDSVersion

messageVersion

The 3D version

directoryResponse

transStatus

(after ARes)

Transaction status after ARes

authenticationResponse

transStatus

(after RReq)

Transaction status after RReq

threeDSTransactionId

threeDSServerTransID

Universally unique transaction identifier.

cardHolderInfo

cardholderInfo

Text provided by the ACS/Issuer to Cardholder

transStatusReason

transStatusReason

Provides information on why the Transaction Status field has the specified value.

Directory Response (Transaction status after ARes)

Value

3Dv2

Y

authenticated

N

authentication failed

U

not available

C

challenge needed

R

rejected

A

authentication attempt

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

Value

3Dv2

Y

authenticated

N

authentication failed

U

not available

A

authentication attempt

C

process 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.