This page describes callback functions being invoked on certain Secure Field events. Use the secureFields.on(...) callback function to subscribe to one or multiple events.

Ready

The event ready will be emitted once the iFrames are loaded.

secureFields.on("ready", function() {
  // Placeholder for the card number field
  secureFields.setPlaceholder("cardNumber", "Card Number");
    
  // Placeholder for the card security number
  secureFields.setPlaceholder("cvv", "Security Code");
});

Validate

The event validate will be emitted once the form was submitted with secureFields.submit();.

secureFields.on("validate", function(event) {
  // Add a red border if a field is invalid 
  secureFields.setStyle("cardNumber.invalid","border: 1px solid #f00");
  secureFields.setStyle("cvv.invalid","border: 1px solid #f00");
});

The event validate contains the length and the validity of both the card number and the card security code, the card's brand, and whether there is an invalid input.

{
  "fields": {
    "cardNumber": {
      "length": 0,
      "valid": false,
      "paymentMethod": "VIS"
    },
    "cvv": {
      "length": 3,
      "valid": true
    }
  },
  "hasErrors": true
}

Success

The event success will be emitted if the transaction was successful. From there you can continue with the finalization of the transaction.

secureFields.on("success", function(data) {
  if(data.transactionId) {
    // Continue with the finalization of the transaction
  }
});

The event success returns all relevant information related to the transaction. 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.

{
  "event":"success",
  "data": {
      "transactionId":"{transactionId}",
      "cardInfo": {
          "brand":"MASTERCARD",
          "type":"credit", // debit or credit
          "usage":"consumer", // consumer, corporate or unknown
          "country":"CH", // 2 letter ISO 3166-1 alpha-2 country code
          "issuer":"DATATRANS"
      },
      "redirect":"https://pay.sandbox.datatrans.com/upp/v1/3D2/{transactionId}"
  }
}

Clear

The event clear will be emitted if the function secureFields.clear(field) was used.

$("#cvvClear").click(function () {
  secureFields.clear("cvv");
});

secureFields.on("clear", function(event) {
  // your magic
});

The event clear returns which fields where deleted.

{
  "fields": {
    "cardNumber": {
      "length": 0,
      "valid": false
    },
    "cvv": {
      "length": 0,
      "valid": false
    }
  },
  "hasErrors": true,
  "event": {
    "field": "cvv",
    "type": "clear"
  }
}

Change

The event change will be emitted whenever one of the following events are triggered:

onkeyup
onkeydown
onblur
touchstart
touchmovetouchend
touchcancel
touchforcechange
autocomplete (see Browser autofill)

secureFields.on("change", function(event) {
  // your fancy stuff
});

The event change returns the following structure:

{
  "fields": {
    "cardNumber": {
      "length": 0,
      "valid": false,
      "paymentMethod": "VIS"
    },
    "cvv": {
      "length": 0,
      "valid": false
    }
  },
  "hasErrors": true,
  "event": {
    "field": "cardNumber",  // the affected input field
    "type": "blur"          // the original event
  }
}

Browser autofill

Events of type autocomplete are triggered if a user makes use of their browser's integrated credit card autofill feature which typically provides expiry month and year alongside credit card number and cvv. While you should never come in touch with the latter, expiry data can be captured and filled into form fields located on merchant side in order to lower friction for the user during the payment process.

// expiry month provided via browser autofill
{
  // ...
  "event": {
    "type": "autocomplete",
    "field": "expiryMonth",
    "value": "12"    
  }
}

// expiry year provided via browser autofill
{
  // ...
  "event": {
    "type": "autocomplete",
    "field": "expiryYear",
    "value": "2021"    
  }
}

Code sample on how to react to autocomplete events:

var expiryMonth, expiryYear;

secureFields.on("change", function(data) {
  var event = data.event;
  
  if (event.type === "autocomplete") {
    if (event.field === "expiryMonth") {
      expiryMonth = event.value; // "12"
      return;
    }
    
    if (event.field === "expiryYear") {
      expiryYear = event.value.slice(-2); // "2021" (note: take the last two digits for MM/YY)
      return;
    }
  }
});

Error

The event error will be emitted if there was an error after calling secureFields.submit().

Possible errors are:

You are using a wrong merchantId in secureFields.submit().
The card number or security code fields are named incorrectly.
There is a wrong merchant configuration.

secureFields.on("error", function(data) {
  // something bad happened
});