Secure Fields (iframes)

Secure Fields allow you to securely collect credit, debit and virtual cards as well as bank account data by injecting iframes to your DOM. A separate iframe for all sensitive values is used. Thereby, the data never touches your server and allows you to capture all other related payment data such as cardholder name, expiry date, etc. directly by yourself.
Using Secure Fields qualifies you for SAQ A.
Browser compatibility for Secure Fields:
Browser
Version
Chrome | Chrome Mobile
>=28 | >=28
Firefox | Firefox Mobile
>=31 | >=31
Internet Explorer | Internet Explorer Mobile
>=9 | >= 9
Safari | Safari Mobile
>=6 | >=6
Opera | Opera Mobile
>=24 | >=22
Blackberry Browser
>=8
Android Browser
>=4
1. Setup Secure Fields
To get started include the following script on your page. 
Secure Fields Script
Minified Version
Secure Fields 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​
2. 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
For the bank account example they are
iban-placeholder
account-number-placeholder
branch-number-placeholder
Card number / CVV
IBAN 
Account number / Branch code
Card number / CVV
<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>
IBAN 
<form>
    <div>
        <div>
            <label for="iban-placeholder">IBAN</label>
            <!-- IBAN container -->
            <div id="iban-placeholder" style="width: 250px;"></div>
        </div>
​
        <button type="button" id="go">Get Token!</button>
    </div>
</form>
Account number / Branch code
<form>
    <div>
        <div>
            <label for="account-number-placeholder">account number</label>
            <!-- account number container -->
            <div id="account-number-placeholder" style="width: 90px;"></div>
        </div>
        <div>
            <label for="branch-code-placeholder">branch code</label>
            <!-- branch code container -->
            <div id="branch-code-placeholder" style="width: 90px;"></div>
        </div>
​
        <button type="button" id="go">Get Token!</button>
    </div>
</form>
In test mode, only test credentials are allowed.
3. Retrieve a Transaction ID
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 merchantId and specify which DOM element containers should be used to inject the iframes:
Card number / CVV
IBAN
Account number / Branch code
Card number / CVV
secureFields.initTokenize( "1100007006", {
  cardNumber: "card-number-placeholder", 
  cvv: "cvv-placeholder"                
});
IBAN
secureFields.initTokenize( "1100007006", {
  iban: "iban-placeholder"               
});
Account number / Branch code
secureFields.initTokenize( "1100007006", {
  accountNumber: "account-number-placeholder",
  branchCode: "branch-code-placeholder"               
});
Afterwards submit the form and listen for the success event:
$(function() {
  $("#go").click( function() {
    secureFields.submit(); // submit the "form"
  })
});
​
secureFields.on("success", function(data) {
  if(data.transactionId) {
    // transmit data.transactionId and the rest
    // of the form to your server    
  }
});
Instances can be destroyed if no longer used:
secureFields.destroy();
4. Obtain tokens
Once you've transmitted the transactionId to your server (together with the the rest of your form) you have to execute a server to server GET Token request to retrieve the tokenized card or bank account values. 
This service requires HTTP basic authentication. The required credentials can be found in our dashboard. Please refer to API authentication data for more information. 
get
Token
https://api.sandbox.datatrans.com/upp/services/v1/inline/token
This endpoint returns the tokenized card or bank account data corresponding to the transactionId.
Please note that this is a server to server API call and cannot be called from the browser directly.
Request
Response
Request
Headers
Authorization
required
string
Basic MTEwMDAwNzAwNjpLNnFYMXUkIQ==
Query Parameters
transactionId
required
integer
The transactionId obtained via the secureFields.submit()operation.
returnPaymentMethod
optional
boolean
Returns payment method used with transaction.
mandatoryAliasCVV
optional
boolean
Wheter the case should be gluten-free or not.
returnCardInfo
optional
boolean
Returns cardInfo object
Response
200: OK
{
  "aliasCC": "AAABcHxr-sDssdexyrAAAfyXWIgaAF40",
  "aliasCVV": "mVHJkLRrRX-vb9uUzEM40RUN",
  "maskedCard": "424242xxxxxx4242"
}
Token API calls examples
Request
Response Card
Response IBAN
Response Account number & Branch code
Request
$ curl "https://api.sandbox.datatrans.com/upp/services/v1/inline/token?transactionId=170419151426624571" \ 
        -u 'merchantId:password'
Response Card
{
  "aliasCC": "AAABeM8yJsbssdexyrAAAXnn_sIdAKe0",
  "fingerprint": "F-dV5V8dE0SZLoTurWbq2HZp",
  "aliasCVV": "mVHJkLRrRX-vb9uUzEM40RUN",
  "maskedCard": "424242xxxxxx4242"
}
Response IBAN
{
    "aliasIban": "AAABeKaD2UbssdexyrAAAUN24QvOZg3n",
    "maskedIban": "DE85xxxxxxxxxxxxxx2345"
}
Response Account number & Branch code
{
    "aliasAccountNumber": "AAABeKahwGDssdexyrAAAV8w_R0dlq9b",
    "maskedAccountNumber": "xxxx0604",
    "aliasBranchCode": "AAABeKahwGDssdexyrAAAadGCQEwl6MZ"
}
Example: returnPaymentMethod=true returning paymentMethod
Response
Example: returnPaymentMethod=true returning paymentMethod
$ curl "https://api.sandbox.datatrans.com/upp/services/v1/inline/token?transactionId=170419151426624571&returnPaymentMethod=true" \
       -u 'merchantId:password'
Response
{
  "aliasCC": "AAABcHxr-sDssdexyrAAAfyXWIgaAF40",
  "aliasCVV": "mVHJkLRrRX-vb9uUzEM40RUN",
  "paymentMethod": "VIS",
  "maskedCard": "424242xxxxxx4242"
}
Example: mandatoryAliasCVV=true w/ transactionId that has no CVV token
Response
Example: mandatoryAliasCVV=true w/ transactionId that has no CVV token
$ curl "https://api.sandbox.datatrans.com/upp/services/v1/inline/token?transactionId=170822090245534063&mandatoryAliasCVV=true" \
       -u 'merchantId:password'
Response
400 Bad Request
Tokenization with CVV not found
Example: returnCardInfo=true returning CardInfo 
Response
Example: returnCardInfo=true returning CardInfo 
curl -L -X GET 'https://api.sandbox.datatrans.com/upp/services/v1/inline/token?transactionId=210202095141262032&returnCardInfo=true' \
-H 'merchantId:password'
Response
{
    "aliasCC": "AAABeM8yJsbssdexyrAAAXnn_sIdAKe0",
    "fingerprint": "F-dV5V8dE0SZLoTurWbq2HZp",
    "aliasCVV": "ScRuEmNjRJ682mIGKHA9xx_R",
    "maskedCard": "424242xxxxxx4242",
    "cardInfo": {
        "brand": "VISA CREDIT",
        "type": "credit",
        "usage": "consumer",
        "country": "GB",
        "issuer": "DATATRANS"
    }
}
Error table 
Error message
Cause / Explanation
Tokenization expired
The transactionId has expired. Please note that it is valid for 30 minutes only.
Tokenization not found
The merchant id used for the transaction id creation does not match the merchant id used for the GET Token call.
Examples
Please visit our GitHub repository for additional examples of integration versions: 

Demo Basic: https://datatrans.github.io/secure-fields-sample/
Demo with horizontal fields: https://datatrans.github.io/secure-fields-sample/inline-example.html
Demo with floating labels: https://github.com/datatrans/secure-fields-sample/blob/master/floating-label.html​
An example of how to implement this behaviour in modern web applications can be found here​
In test mode, only test credentials are allowed.
Please also have a look at Styling and Events references.
Next up
Use stored cards
/use-stored-cards
​
PUSH Method
Initialization and Styling
Last updated 5 days ago
Browser	Version
Chrome \| Chrome Mobile	>=28 \| >=28
Firefox \| Firefox Mobile	>=31 \| >=31
Internet Explorer \| Internet Explorer Mobile	>=9 \| >= 9
Safari \| Safari Mobile	>=6 \| >=6
Opera \| Opera Mobile	>=24 \| >=22
Blackberry Browser	>=8
Android Browser	>=4
Error message	Cause / Explanation
Tokenization expired	The `transactionId` has expired. Please note that it is valid for 30 minutes only.
Tokenization not found	The merchant id used for the transaction id creation does not match the merchant id used for the GET Token call.
Secure Fields (iframes)

1. Setup Secure Fields

2. Create payment form

3. Retrieve a Transaction ID

4. Obtain tokens

getToken

Token API calls examples

Error table

Examples

Next up

get
Token
