SecureFields 3D (beta)

Use Secure Fields integration for Tokenisation and Authentication only in your frontend.

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/secureFields
Initial Server-to-Server call to retrieve transactionId and submit 3D v1/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 amount in the currency's smalles unit. For example use 1000 for EU 10.00
currency
required
string
3 letter ISO-4217 character. For example CHF or USD
returnUrl
required
string
Your 3D process return URL
card
optional
object
Object used for additional 3D v2 parameters
Response
201: Created
{
"transactionId": "190520110934541218",
}
400: Bad Request
Amount must be at least in the currency's smallest unit.
{
"error": {
"code": "INVALID_PROPERTY",
"message": "init.amount must be > 0"
}
}

Refer to the official EMVCo 3D specification 2.1.0 for parameter requirements sent in the card object. https://www.emvco.com/emv-technologies/3d-secure/

The transactionId returned in the response of the init call

{
"transactionId": "190520110934541218",
}

Examples

Request
Response
Request
curl -v -u 1100018081:2fgVhQOYZK0io9ct 'https://api.sandbox.datatrans.com/v1/transactions/secureFields' \
-H 'Content-Type: application/json; charset=UTF-8' \
-d '{
"amount" : 1000,
"currency" : "EUR",
"returnUrl": "https://pay.sandbox.datatrans.com/upp/merchant/successPage.jsp",
"card": {
"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": {}
}
}
}'
Response
{
"transactionId" : "190510170631533875"
}

Step 2: Setup SecureFields

To get started include the following script on your page.

SecureFields Script
Minified version
SecureFields Script
<script src="https://pay.sandbox.datatrans.com/upp/payment/js/secure-fields-2.0.0.js"></script>
Minified version
<script src="https://pay.sandbox.datatrans.com/upp/payment/js/secure-fields-2.0.0.min.js"></script>

Please make sure to always load it directly from https://pay.sandbox.datatrans.com

Step 3: Create payment form

In order for Secure Fields to insert card number and CVV iframes at the right place, create empty DOM elements and assign them unique IDs. In the example below those are:

  • card-number-placeholder

  • cvv-placeholder

<form>
<div>
<div>
<label for="card-number-placeholder">Card Number</label>
<!-- card number container -->
<div id="card-number-placeholder" style="width: 250px;"></div>
</div>
<div>
<label for="cvv-placeholder">Cvv</label>
<!-- cvv container -->
<div id="cvv-placeholder" style="width: 90px;"></div>
</div>
<button type="button" id="go">Get Token!</button>
</div>
</form>

Step 4: Initialize Secure Fields with the transactionId

Start with creating a new Secure Fields instance:

var secureFields = new SecureFields();
// Multiple instances might be created and used independently:
// e.g. var secureFields2 = new SecureFields();

Initialize it with your transactionId and specify which DOM element containers should be used to inject the iframes:

secureFields.init(
'190520110934541218',
{
cardNumber: {
placeholderElementId: 'card-number-placeholder',
inputType: 'tel'
},
cvv: {
placeholderElementId: 'cvv-placeholder',
inputType: 'tel'
}
},
{
debug: true
}
);

Afterwards add parameter expm and expy , submit the form and listen for the success event:

$(function() {
$("#go").click( function() {
secureFields.submit({ // submit the "form"
expm: 12,
expy: 21
});
});
});
secureFields.on("success", function(data) {
if(data.transactionId) {
// transmit data.transactionId and the rest
// of the form to your server.
// redirect the customers browser to the URL
// within data.redirect. See Step 5.
}
});

Step 5: Display a 3D secure challenge

The success event returns a redirect attribute which contains the 3D URL. To present a challenge flow, redirect the card holder to this URL to trigger 3D authentication process. Once the card holder completed the 3D process, he will be redirected to the returnUrl passed to the /v1/transactions/secureFields API.

Step 6: Obtain 3D parameters and tokens

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 MTEwMDAwNzAwNjpLNnFYMXUklq== see Setup
Query Parameters
transactionId
required
string
The transactionId obtained via initial/v1/transactions/secureFields call
Response
200: OK
Returns Creditcard and CVV code tokens as well as the "3D" object
Example response
{
"transactionId": "190520111958152753",
"type": "payment",
"status": "authenticated",
"currency": "CHF",
"refno": "N/A",
"paymentMethod": "ECA",
"detail": {
"authorize": {
"amount": 10
}
},
"card": {
"alias": "520000RIVWAS0080",
"masked": "520000xxxxxx0080",
"aliasCVV":"WWguOT-vQKybTMo1CALTjjwZ",
"expiryMonth": "12",
"expiryYear": "21",
"3D": {
"eci": "02",
"xid": "MDAxOTA1MjAxMTE5NTgxNTI3NTM=",
"cavv": "OTkxOTA1MjAxMTIxMDU2MTI4NzM=",
"threeDSVersion": "1.0.2",
"directoryResponse": "Y",
"authenticationResponse": "A"
}
}
}

Examples

Request
Response
Request
curl -u 1100018081:2fgVhQOYZK0io9ct https://api.sandbox.datatrans.com/v1/transactions/190510164649321735
Response
{
"transactionId": "190520111958152753",
"type": "payment",
"status": "authenticated",
"currency": "EUR",
"refno": "N/A",
"paymentMethod": "ECA",
"detail": {
"authorize": {
"amount": 1000
}
},
"card": {
"alias": "520000RIVWAS0080",
"masked": "520000xxxxxx0080",
"aliasCVV":"WWguOT-vQKybTMo1CALTjjwZ",
"expiryMonth": "12",
"expiryYear": "21",
"3D": {
"eci": "02",
"xid": "MDAxOTA4MDkxNjMzMDkzNTUwMDQ=",
"cavv": "OTkxOTA4MDkxNjMzMTYwNTUwMzY=",
"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 7: Forward 3D data

Received "3D" object contains parameters with the result of the 3D-Secure process and can be forwarded to 3rd party payment gateway. If you decide to use Datatrans payment gateway please continue with our Authorize API.

Examples

Find a working sample here (change transactionId all the time): https://github.com/datatrans/secure-fields-sample/blob/secure-fields-init-with-transactionId/index.html