Our 3D Secure API is suitable for PCI DSS Level 1 merchants or service providers who wish to only use our 3D Secure Authentication services or those who want to decouple card capturing from authentication.

Before you start

🚧
3D Secure Fields requires a 3D Secure enrolled acquiring contract for each card brand.
You will need data provided in this contract when using 3D Secure Fields.

Make sure to also use our 3D Secure-enabled test credit cards and credentials.

💡
Note that all 'amounts' in these APIs are in minor units.
For example, CHF has 2 decimal points, so "amount": 1250 corresponds to 12.50 CHF. For JPY, "amount": 1250 corresponds to 1250 JPY.

1. Initial server-to-server call

To start, send a POST request to our init transaction endpoint. Please refer to the API Reference to get a detailed view of all required and optional fields.

Examples

curl --request POST \
  --url 'https://api.sandbox.datatrans.com/v1/transactions'
  --header 'Authorization: Basic {{basicAuth}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "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."
            },            
            "cardholder": {      
                "email": "[email protected]",
                "cardholderName": "John Doe",
                "mobilePhone": {
                    "cc": "41",
                    "subscriber": "123456789"
                },
                "workPhone": {
                    "cc": "41",
                    "subscriber": "123456789"
                },
                "homePhone": {
                    "cc": "41",
                    "subscriber": "123456789"
                }
            }
        }
    },
    "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 --request POST \
  --url 'https://api.sandbox.datatrans.com/v1/transactions' \
  --header 'Authorization: Basic {{basicAuth}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1000,
    "currency": "EUR",
    "refno": "NIJ3OSelzyqp",
    "paymentMethods": [
        "ECA"
    ],
    "card": {
        "number": "5200000000000080",
        "cvv": "123",
        "expiryMonth": "06",
        "expiryYear": "25",
        "3D": {
            "acquirer": {
                "acquirerMerchantId": "1234567",
                "acquirerBin": "9876543"
            },
            "merchant": {
                "mcc": "4722",
                "merchantName": "Example Travel Ltd."
            },
            "cardholder": {
                "billAddrCity": "Paris",
                "billAddrCountry": "642",
                "billAddrLine1": "",
                "billAddrPostCode": "123456",
                "billAddrState": "",
                "email": "[email protected]",
                "cardholderName": "Jeni",
                "mobilePhone": {
                    "cc": "41",
                    "subscriber": "123456789"
                },
                "workPhone": {
                    "cc": "41",
                    "subscriber": "123456789"
                },
                "homePhone": {
                    "cc": "41",
                    "subscriber": "123456789"
                }
            }
        }
    },
    "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"
    }
}'

🚧
Mandatory Data for 3DS Processing
As of 1st April 2026, Mastercard have updated their data requirements for 3DS authentication processing. These broadly align with the requirements that Visa outlined at the end of 2024. The result is that some fields that were previously required only in certain conditional circumstances, must now be provided in all cases.
You must provide valid consumer data in your initial requests. The mandatory and optional parameters are within the 3D object nested inside card.3D.cardholder for init requests. In addition to the required fields, other parameters are strongly recommended to be sent. Please refer to our init endpoint documentation for further details and technical specifications.
Required fields
Cardholder Name (3D.cardholder.cardholderName)
Billing Address Line 1 (3D.cardholder.billAddrLine1)
At least one of the following:
Cardholder Email Address (3D.cardholder.email)
Cardholder Home Phone Number (3D.cardholder.homePhone)
Cardholder Mobile Number (3D.cardholder.mobilePhone)
Cardholder Work Number (3D.cardholder.workPhone)
At least one of the following:
IP Address (browser or device) (3D.browserInformation.browserIP)
Device ID (3D.browserInformation.deviceID)
Strongly recommended fields
Shipping Address Line 1 (3D.cardholder.shipAddrLine1)
Cardholder Billing Address Postal Code (3D.cardholder.billAddrPostCode)
Cardholder Billing City (3D.cardholder.billAddrCity)
Cardholder Billing State (3D.cardholder.billAddrState)
Cardholder Billing Country (3D.cardholder.billAddrCountry)
Browser Screen Height (3D.browserInformation.browserScreenHeight)
Browser Screen Width (3D.browserInformation.browserScreenWidth)
Browser Language (3D.browserInformation.browserLanguage)
Browser Time Zone (3D.browserInformation.browserTZ )

In the response, you will find:

Location header: https://pay.sandbox.datatrans.com/v1/start/{{transactionId}}
Response body:

{
	"transactionId": "{{transactionId}}",
	"3D": {
		"enrolled": true
	}
}

Error codes

If the initialization failed, you will receive one of the error codes listed in card network errors.

2. Display a 3D Secure Challenge

The Location header is where the cardholder should be redirected to trigger the 3D Secure Authentication process. Once the cardholder completes the 3D Secure Authentication, they will be redirected to the successURL which was initially passed to the API in step 1.

We send a postMessage to the parent before redirecting to ACS, thus, our pages can be hidden until the redirect to ACS happens.
parent.postMessage("redirectingToACS", "*");

3. Obtain 3D Secure parameters

To get the results of the 3D Secure Authentication, call our Status API.

Example

curl --request GET \
  --url 'https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}' \
  --header 'Authorization: Basic {{basicAuth}}'

{
  "transactionId": "{{transactionId}}",
  "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": "1f88043a-7d5c-431b-be5d-bfebd6088992",
      "cavv": "OTkxOTA4MDkxNjMzMTYwNTUwMzY=",
      "threeDSVersion": "2.2.0",
      "directoryResponse": "Y",
      "authenticationResponse": "Y",
      "transStatusReason": "01",
      "cardHolderInfo": "Detailed issuer notification if available",
      "threeDSTransactionId": "8558c931-277b-4240-adfc-443cbd61a2c0"
    }
  }
}

For details on the meaning of fields, see Technical details and 3D Secure object field mapping.

4. Forward 3D Secure Authentication data

In the response you will see a card.3D object which contains 3D Secure details that can be forwarded to a third-party payment gateway. If you are using Datatrans as a payment gateway, you can continue with the Authorize API.