3D Secure Fields
Run 3DS Authentications when collecting card data on your web page.
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.
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. 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 https://api.sandbox.datatrans.com/v1/transcations/secureFields
.
In the 3D Secure 2 framework, you can optionally send additional data to increase acceptance rates or frictionless flow rates.
See Technical details for more information and refer to the official EMVCo 3D specification for parameter requirements sent in the card brand object. Contact us if you need some more information.
3D Secure acquirer data
To use the Authentication only API, you will ned 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"
}
}
},
"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"
}
}
}
}'
{
"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.
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
, andstatus_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.
Updated about 1 month ago