The developer.datatrans.com Developer Hub

Welcome to the developer.datatrans.com developer hub. You'll find comprehensive guides and documentation to help you start working with developer.datatrans.com as quickly as possible, as well as support if you get stuck. Let's jump right in!

Secure Fields

Secure Fields offer you maximum design freedom with minimal compliance effort. Secure Fields are secure iFrames which you can use to capture card information from your customers while also ensuring sensitive card data never comes into contact with your systems. Two iFrames will have to be injected to your page: One for the card number and another for the card security code. Your systems will never touch any sensitive information and you will be able to keep almost all card payment interactions on your page. While this integration requires some more effort on your side compared to our Redirect or Lightbox integration, you can offer a seamless experience for card payments. Please note the minimum browser versions needed to support our Secure Fields.



32



12 (IE: 11)



30



7 (iOS: 6)

Only card payments are supported

Our Secure Fields integration support card payments only. Please check the payment method overview to see which cards are currently supported.

Secure Fields Integration

To get started include our Secure Fields script on your web page.

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

Next, you'll want to insert the card number and card security code iFrames at your desired location. Create empty DOM elements and assign a unique CSS ID to each of them. In the example, the unique IDs are card-number-placeholder and cvv-placeholder.

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

Initializing Transactions

To create a payment with Secure Fields, you will need to initialize a transactionId. Call our secureFieldsInit endpoint with your desired parameters and we'll return a transaction identifier ready to be used with our Secure Fields. The parameter returnUrl specifies where the browser should be redirected to after a 3D Secure authentication. Please note that a transactionId is only valid for 30 minutes. If you wish to do a dedicated registration, you must omit the parameter amount. Please read our section saving payment information for more details.

curl 'https://api.sandbox.datatrans.com/v1/transactions/secureFields' \
--header 'Authorization: Basic {{basicAuth}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"amount": 100,
	"currency": "CHF",
	"returnUrl": "{{returnUrl}}"
}'

Initializing our Javascript Library

Now that you have a transactionId, you can initialize the Secure Fields JavaScript library and specify which DOM element containers should be used to inject the iframes.

var secureFields = new SecureFields();
secureFields.init(
  {{transactionId}}, {
      cardNumber: "cardNumberPlaceholder",
      cvv: "cvvPlaceholder",
  });

Success & 3D Secure

Within the event success you can handle the data recevied after the secureFields.submit() call. If 3D authentication is required for a specific transaction, the parameter redirect inside the object data will indicate the URL that the customer needs to be redirected to. Below is an example of the success event data. Refer to the section Secure Fields Events to see all possible events.

{
  "event":"success",
  "data": {
      "transactionId":"{transactionId}",
      "cardInfo":{"brand":"MASTERCARD","type":"credit","usage":"consumer","country":"CH","issuer":"DATATRANS"},
      "redirect":"https://pay.sandbox.datatrans.com/upp/v1/3D2/{transactionId}"
  }
}

Finalizing the Authorization

To finalize any transaction with our Secure Fields you need to call our authorize-split endpoint. Here you can specify if the transaction should be settled automatically or if you wish to proceed with a deferred settlement.

curl 'https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/authorize' \
--header 'Authorization: Basic {{basicAuth}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"refno": "Test-1234",
	"amount": 100,
	"autoSettle": true
}'

Example

Below is a simple payment form created with Secure Fields. Have a look at our dedicated page Styling & Initialization Options to see what options you have to style and initialize the library. For the sake of simplicity, other important fields like amount, expiry, and cardholder name are omitted. Please refer to our Github sample for more detailed examples.

PCI Proxy Web Tokenization

            

Updated about a month ago

Secure Fields


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.