The Developer Hub

Welcome to the developer hub. You'll find comprehensive guides and documentation to help you start working with 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.


12 (IE: 11)


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.

Process Overview

To start a transaction via our Secure Fields integration, you will need to call our secureFieldsInit endpoint ¹ to receive a transactionId ². For any new operation, you should retrieve a new transactionId. A transactionId is valid for 30 minutes. The transactionId can now be sent to your frontend and used to start the Secure Fields Javascript library ³. Once your customer completes the required information in your UI, you can submit the form's content ⁴. After submitting the form we will inform you if 3D Secure is required or not. If 3D Secure is required to complete the payment, you will have to redirect the customer to a specific URL provided by the cardholder's bank (ACS) ⁵. Upon completion of the 3D Secure authentication, we will automatically redirect the customer to the returnUrl specified in the secureFieldsInit request. To finalize the transaction, call the split-authorize endpoint ⁶.

Secure Fields Integration

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

<script src=""></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.

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

Initializing Transactions

To create a payment with Secure Fields, you will need to initialize a transactionId via a server-to-server call first. 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 '' \
--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",

Submitting your form

Use the submit function to submit the card information. Don't forget to also submit the expiry month and the expiry year of the card. These two items are not subject to PCI compliance, so you will have to collect them without injecting our iFrames.

  		expm: 12, // ask for the expiry month in your form
  		expy: 25 // ask for the expiry year in your form

Success & 3D Secure

Within the event success you can handle the data received 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. This URL is provided by the cardholder's bank (ACS). Upon completion of the 3D Secure authentication, we will automatically redirect the customer to the returnUrl specified in the secureFieldsInit request. The returnUrl will also contain a parameter called status_3d stating the result of the 3D Secure authentication process. The possible authentication response values are outlined in the 3D Secure section in our docs.

Below is an example of the success event data. Refer to the section Secure Fields Events to see all possible events.

  "data": {
      "cardInfo": { 

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 '{{transactionId}}/authorize' \
--header 'Authorization: Basic {{basicAuth}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"refno": "Test-1234",
	"amount": 100,
	"autoSettle": true


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.