The Secure Fields allow you to securely collect card data by injecting iframes to your DOM. A separate iframe for both, card number and CVV code is used. Thereby, sensitive data never touches your server and allows you to capture all other related card data such as cardholder name, expiry date, etc. directly by yourself. Compared to Lightbox or Redirect Mode the integration effort is higher. However, Secure Fields are giving you the most flexibility when implementing your checkout flow.

🚧

Secure Fields support credit cards only and are meant to be used if the payment method selection happens on the merchant website. If you want to use Secure Fields in combination with other payment methods please check the documentation for the corresponding payment method.

Browser compatibility

Firefox >= 30
Chrome >= 32
Edge >= 12
Chrome for Android >= 32
Safari >= 7
iOS Safari >= 6
Internet Explorer >= 11

Setup your Secure Fields

To get started include the following script on your page.

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

Create a payment form

In order for the Secure Fields to insert the 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 and 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">Pay!</button>
    </div>
</form>

# Retrieve a transactionId
Initialize the Secure fields with your merchantId and specify which DOM element containers should be used to inject the iframes:

var secureFields = new SecureFields();
secureFields.initPay( "your merchantId", {
  cardNumber: "card-number-placeholder",
  cvv: "cvv-placeholder"
});

Use the secureFields.initRegister function if you only need to register your card holder. In addition the amount parameter in the submit function (see below) can be omitted.

Afterwards submit the form and listen for the success event:

var secureFields = new SecureFields();
$(function() {
    $("#go").click( function() {
        secureFields.submit({
            amount: 1000, // ask for the amount in your form
            expm: 12, // ask for the expm in your form
            expy: 21, // ask for the expy in your form
            currency: "CHF",
            returnUrl: "your return url" // 3D process return URL
        });
    })
});

secureFields.on("success", function(data) {
    if(data.transactionId) {
        // transmit data.transactionId and the rest
        // of the form to your server    
    }
});

Below a simple payment form created with Secure Fields. For the sake of simplicity, other important fields like amount, expiry and cardholder name are omitted.

3D Secure

The success event will indicate if a redirect to the card holders 3D provider is needed or not. The callback object will hold a redirect attribute in case 3D is mandatory. There will be no redirect attribute in case the card is not enrolled or the merchant does not have a 3D contract.

{
  redirect: "url",
  result: "success",
  transactionId: "180418150901198791"
}

Redirecting the card holder to the URL provided in the redirect property is mandatory. Once the card holder completed the 3D process, he will be redirected to the returnUrl passed to the secureFields.submit function. The corresponding 3D status will also be sent to this returnUrl within parameter status_3d. This parameter can hold the following values:

Use the transactionId to make a payment or a card check

Once you've transmitted the transactionId to your server (together with the rest of your form data) you can execute a server to server call to make a payment.

curl https://api.sandbox.datatrans.com/upp/jsp/XML_authorizeSplit.jsp \
  -H "Content-Type: application/xml" \
  -d "@request.xml"

Where the payload (request.xml) could have the following content for a credit card payment method:

<?xml version="1.0" encoding="UTF-8" ?>
  <authorizationSplit version="4">
    <body merchantId="your merchantId">
      <transaction refno="your refno">
        <request>
          <uppTransactionId>TRANSACTION-ID</uppTransactionId>
          <currency>CHF</currency>
          <amount>1000</amount>
        </request>
      </transaction>
    </body>
  </authorizationSplit>

Use <amount>0</amount> to only check if the card is valid. This can be useful in cases where only a registration takes place.

🚧

The Split Payment API endpoint is used to 'finalise' a Secure Fields transaction.

Security

Please enable Server to Server security (Basic authentication) in our Datatrans Backoffice Tool to properly protect your final payment or card check call. You can find the settings under UPP Administrations > Security > Server-to-Server services security.