Subscribe Pro Vault Hosted Iframe Events

The Subscribe Pro Vault Hosted Iframe fires numerous events during its lifecycle. You can register event handlers for these events using the IframeClient.on() method.

List of Events

The following events are fired by the Subscribe Pro Vault Hosted Iframe:

eventNameDescription
initializedFired when the iframe client has been initialized.
inputEventFired when an input event occurs in the iframe.
errorFired when an error occurs.
validationResultChangedFired when validation has occurred and the result has changed.
tokenizeFired when the tokenize() method completes.

Event: initialized

This event if fired after the hosted iframe library is completely initialized and ready to use.

No arguments are passed to the callback function.

Example

IframeClient.on('initialized', () => {
  console.log('Iframe was initialized.');
});

Event: inputEvent

This event is fired when certain events are fired by the <input> field elements inside the hosted iframes.

Example

IframeClient.on('inputEvent', (args) => {
  console.log('Iframe inputEvent received.', args);
});

Example of args

{
  "fieldCode": "number",
  "eventType": "focus"
}

Properties of the args Object (for inputEvent)

PropertyTypeDescription
fieldCodeStringIndicates which field has fired the event: number, cvv, account or other.
eventTypeStringThe name of the event which was fired by the browser on the <input> element. The following events are passed through: focus, blur, input.

Event: error

Event is currently not fired, but is reserved as a placeholder for future versions of the hosted iframe.

Example

IframeClient.on('error', (args) => {
  console.log('Iframe error received.', args);
});

Event: validationResultChanged

Event is fired when validation has occurred and the result has changed (for example when a card number goes from being invalid to valid).

Example

IframeClient.on('validationResultChanged', (args) => {
  console.log('In on.validationResultChanged.');
  console.log(args?.validationResult);
});

Example of args

{
  "validationResult": {
    "cardType": "american_express",
    "isNumberValid": true,
    "isNumberPotentiallyValid": true,
    "isCvvValid": false,
    "isCvvPotentiallyValid": true
  }
}

Properties of the args.validationResult Object (for validationResultChanged)

PropertyTypeDescription
cardTypeStringDetected credit card type: 'visa', 'american_express', 'master', etc.
isNumberValidBooleanIs the card number fully validated.
isNumberPotentiallyValidBooleanIs the card number potentially valid - meaning it is partially populated and so far the digits conform to a known credit card format.
isCvvValidBooleanIs the card code (CVV) fully validated.
isCvvPotentiallyValidBooleanIs the card code (CVV) potentially valid.

Event: tokenize

Event is fired when tokenization of the sensitive payment data is complete. Event will return details about success or failure of the tokenization operation as well as details about the tokenized payment data.

Example

IframeClient.on('tokenize', (result) => {
  console.log('Iframe tokenize received.', result);
});

Example of result

{
  "isSuccessful": true,
  "token": {
    "id": "XXXX",
    "environmentId": "XXXX",
    "tokenString": "XXXX",
    "creditCard": {
      "cardType": "visa",
      "isNumberValid": true,
      "isCvvValid": true,
      "cardIssuerIdentificationNumber": "411111",
      "cardLastDigits": "1111"
    },
    "createdAt": "2023-08-21T18:29:57.799Z",
    "updatedAt": "2023-08-21T18:29:57.799Z"
  }
}

Properties of the result Object

PropertyTypeDescription
isSuccessfulboolIndicates if tokenization of the sensitive payment data was successful.
token.idstringThis is the token ID which uniquely identifies the tokenized payment data in the Subscribe Pro Vault. This value is a UUID.
token.environmentIdstringThis is the Subscribe Pro Vault environment ID where the token data is stored. This value is a UUID.
token.tokenStringstringThis is the token string which uniquely identifies the tokenized payment data.
token.creditCardobjectThis property is present when the tokenized payment data represents a credit card. It contains details about the credit card.
token.creditCard.cardTypestringCredit card brand type. Only included if the card number is valid. For example: visa
token.creditCard.cardIssuerIdentificationNumberstringThis is the Bank Identification Number (BIN) of the credit card. This is typically the first 6 digits of the credit card number. For example: 411111
token.creditCard.cardLastDigitsstringThis is the last 4 digits of the credit card number. For example: 1111
token.creditCard.isNumberValidboolIs the credit card number valid (based on Luhn algorithm check).
token.creditCard.isCvvValidboolIs the credit card CVV valid.
token.createdAtstringDate/time stamp representing when the tokenized payment data was created.
token.updatedAtstringDate/time stamp representing when the tokenized payment data was last updated.