Our Secure Fields allows you to also perform 3DS Authentications on your web page whilst collecting and tokenizing sensitive card data. Follow this guide to get set up. If you already have Secure Fields set up, there are only a few more steps.

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.

💡

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.

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

1. Initiate server-to-server call

To start a 3D Authentication in Secure Fields, you will first need to make a server-to-server call to v1/transactions/secureFields. Please refer to the API Reference to get a detailed view of all required and optional fields.

3D Secure acquirer data

To use the Authentication only API, you will need to obtain the following data fields from your acquirer, as they are part of the 3D Secure 2 enrolment process with the card schemes.

Example

curl --request POST \
  --url 'https://api.sandbox.datatrans.com/v1/transactions/secureFields' \
  --header 'Authorization: Basic {{basicAuth}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1000,
    "currency": "EUR",
    "returnUrl": "https://pay.sandbox.datatrans.com/upp/merchant/successPage.jsp",
    "VIS": {
        "3D": {
            "acquirer": {
                "acquirerBin": "658942",
                "acquirerMerchantId": "XCGHPB1U0ZIK459"
            },
            "merchant": {
                "mcc": "4722",
                "merchantName": "Test-OTA"
            },
            "cardholder": {
                "email": "[email protected]",
                "cardholderName": "",
                "mobilePhone": {
                    "cc": "",
                    "subscriber": ""
                },
                "workPhone": {
                    "cc": "",
                    "subscriber": ""
                },
                "homePhone": {
                    "cc": "",
                    "subscriber": ""
                }
            }
        }
    },
    "ECA": {
        "3D": {
            "acquirer": {
                "acquirerBin": "357941",
                "acquirerMerchantId": "XLKDPB1U0ZIK658"
            },
            "merchant": {
                "mcc": "4722",
                "merchantName": "Test-OTA"
            }
        }
    },
    "AMX": {
        "3D": {
            "acquirer": {
                "acquirerBin": "",
                "acquirerMerchantId": "9999999999"
            },
            "merchant": {
                "mcc": "4722",
                "merchantName": "Test-OTA"
            }
        }
    }
}'

🚧

Visa: Mandatory Data for 3DS Processing

Starting from 12th August 2024, Visa will require various data fields to be mandatory for 3DS authentication processing. These fields, previously required only in certain conditional circumstances, must now be provided in all cases. In addition to the required fields, other parameters are strongly recommended to be sent.

These changes aim to enhance authorization success rates and improve fraud prevention measures, making 3DS authentication more seamless and frictionless for customers.

Required fields

• Cardholder Name (3D.cardholder.cardholderName)

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)

{
  "transactionId": "{{transactionId}}"
}

If the initial server-to-server call failed, you will receive one of the error codes listed here.

2. Set up 3D Secure Fields

Follow our 3D Secure Fields recipe:

3. Display a 3D Secure Challenge

The success event returns a redirect attribute which contains a URL to redirect to if a challenge is required. Redirect the cardholder to this URL to trigger the 3D Authentication process.

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", "*");

Once the cardholder has completed the 3D Authentication process, the browser will be redirected to the returnUrl passed to the Secure Fields API (in step 1) , with a POST request containing the variables:

• upptransactionId, and
• status_3d.

4. Obtain 3D Secure parameters and tokens

Execute a server-to-server call with thetransactionId obtained in the first step to obtain the 3D Secure parameters, credit card and CVV tokens.

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": "N/A",
  "paymentMethod": "ECA",
  "detail": {
    "authorize": {
      "amount": 1000
    }
  },
  "card": {
    "alias": "AAABcHxr-sDssdexyrAAAfyXWIgaAF40",
    "fingerprint": "F-dV5V8dE0SZLoTurWbq2HZp",
    "masked": "520000xxxxxx0080",
    "aliasCVV": "WWguOT-vQKybTMo1CALTjjwZ",
    "expiryMonth": "12",
    "expiryYear": "21",
    "info": {
      "brand": "MASTERCARD",
      "type": "credit",
      "usage": "consumer",
      "country": "RO",
      "issuer": "DATATRANS"
    },
    "3D": {
      "eci": "02",
      "xid": "1f88043a-7d5c-431b-be5d-bfebd6088992",
      "cavv": "OTkxOTA4MDkxNjMzMTYwNTUwMzY=",
      "threeDSVersion": "2.1.0",
      "directoryResponse": "Y",
      "authenticationResponse": "Y",
      "transStatusReason": "01",
      "cardHolderInfo": "Detailed issuer notification if available",
      "threeDSTransactionId": "8558c931-277b-4240-adfc-443cbd61a2c0"
    }
  }
}

See 3D Secure object field mapping for explanations of the response fields.

5. Forward 3D Secure 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.

Initialization, Styling and Events

See Initialization and Styling and Events for more information.