Event Handling

Subscribe to Field Events

This function is used to subscribe to events emitted by a Paysafe.js field or fields.

The function signature is as follows:

instance.fields(fieldname).on(events, function(instance, event) {
  ...
})

The function signature contains the following parameters:

Parameter Required Type Description

events

true string

An event name or a list of event names separated by spaces to which the listener applies:

  • Focus
  • Blur
  • Valid
  • Invalid
  • FieldValueChange
  • InvalidCharacter

This parameter is case insensitive.

fieldname true string

The field—or fields separated by spaces—producing events to which to subscribe:

  • cardNumber
  • cvv
  • expiryDate
  • expiryMonth
  • expiryYear

This parameter is case insensitive

callback true function Callback function invoked when an event occurs.
{return} true object The fields handler from which the method was invoked.

An example is shown below:

<html>
  ...
  <body>
    <div id="cardNumber" paysafe="card-number"></div>
    <div id="cvv" paysafe="cvv"></div>
    <div id="expiryDate" paysafe="expiry-date"></div>
    <script>
      let hostedFieldInstance;
      paysafe.fields.setup("my Base64 encoded single-use-token API key", options)
        .then(instance => {
            hostedFieldInstance = instance;
            return hostedFieldInstance.show();
      }).then(paymentMethods => {
            if (paymentMethods.card && !paymentMethods.card.error) {
               hostedFieldInstance.fields("cvv cardNumber expiryDate").on("Focus Blur", function(instance, event) {
                  this.style.borderColor = event.type === "Focus" ? "green" : initialcolor;
               });
            }
      }).catch(error => {
        console.log(error);
      });
    </script>
  </body>
</html>

Async Await Example

<html>
...

<body>
    <div id="cardNumber" paysafe="card-number"></div>
    <div id="cvv" paysafe="cvv"></div>
    <div id="expiryDate" paysafe="expiry-date"></div>
    <script>
        initializeJs();

        async function initializeJs() {
            try {
                const hostedFieldInstance = await paysafe.fields.setup("my Base64 encoded single-use-token API key", options);
                const paymentMethods = await hostedFieldInstance.show();

                if (paymentMethods.card && !paymentMethods.card.error) {
                    hostedFieldInstance.fields("cvv cardNumber expiryDate").on("Focus Blur", function (instance, event) {
                        this.style.borderColor = event.type === "Focus" ? "green" : initialcolor;
                    });
                }
            } catch (error) {
                console.log(error);
            }
        }
    </script>
</body>

</html>

The supported events are listed below:

Event Description

Focus

A field has been selected and is ready to receive input.
Blur A field has been deselected.
Valid A field now contains a valid value.
Invalid A field does not contain a valid value.
FieldValueChange The customer has changed a field's value.
InvalidCharacter The customer has attempted to input a character that is not accepted by this field (for example an alphabetic character)

Alternative Method of Subscribing to Events

You can also subscribe to events using the alternative syntax shown in the function signature below:

instance.fields.<fieldname>.on(events, function(instance, event) {
        ...
})

Replace <fieldname> with a single value from the list below:

  • cardNumber
  • cvv
  • expiryDate
  • expiryMonth
  • expiryYear

The names above are case-sensitive.

The rest of the function has the same as the standard syntax; for example:

<html>
  ...
  <body>
    <div id="cardNumber" paysafe="card-number"></div>
    <div id="cvv" paysafe="cvv"></div>
    <div id="expiryDate" paysafe="expiry-date"></div>
    <script>
      let hostedFieldInstance;
      paysafe.fields.setup("my Base64 encoded single-use-token API key", options)
        .then(instance => {
            hostedFieldInstance = instance;
            return hostedFieldInstance.show();
      }).then(paymentMethods => {
            if (paymentMethods.card && !paymentMethods.card.error) {
                hostedFieldInstance.fields.cvv.on("Focus Blur", function(instance, event) {
                    this.style.borderColor = event.type === "Focus" ? "green" : initialcolor;
                });
            }
      }).catch(error => {
        console.log(error);
      });
    </script>
  </body>
</html>

Async Await example

<html>
    ...
  <body>
    <div id="cardNumber" paysafe="card-number"></div>
    <div id="cvv" paysafe="cvv"></div>
    <div id="expiryDate" paysafe="expiry-date"></div>
    <script>
      initializeJs();

      async function initializeJs() {
        try {
          const hostedFieldInstance = await paysafe.fields.setup("my Base64 encoded single-use-token API key", options);
          const paymentMethods = await hostedFieldInstance.show();

          if (paymentMethods.card && !paymentMethods.card.error) {
            hostedFieldInstance.fields("cvv cardNumber expiryDate").on("Focus Blur", function (instance, event) {
              this.style.borderColor = event.type === "Focus" ? "green" : 'red';
            });
          }
        } catch (error) {
          console.log(error);
        }
      }

    </script>
  </body>

</html>

Subscribe to Instance Events

This function is used to subscribe to events emitted by the Paysafe.js instance. It has the following signature:

instance.on(events, function(instance, event) {
  ...
})

The function signature contains the following parameters:

Parameter Required Type Description

events

true string

An event name—or a list of event names separated by spaces—to which the listener applies; either:

  • Submit
  • CardBrandRecognition
  • BadBin
  • UnsupportedCardBrand

This parameter is case insensitive

callback true function

Callback function invoked when the event occurs.

{return} true object The instance from which the method was invoked.

An example is shown below:

<html>
  ...
  <body>
    <div id="cardNumber" paysafe="card-number"></div>
    <div id="cvv" paysafe="cvv"></div>
    <div id="expiryDate" paysafe="expiry-date"></div>
    <script>
      let hostedFieldInstance;
      paysafe.fields.setup("my Base64 encoded single-use-token API key", options)
        .then(instance => {
            hostedFieldInstance = instance;
            return hostedFieldInstance.show();
      }).then(paymentMethods => {
            if (paymentMethods.card && !paymentMethods.card.error) {
               hostedFieldInstance.on("Submit", function(instance, event) {
                   document.getElementById("pay-button").disabled = instance.areAllFieldsValid();
               });
            }
      }).catch(error => {
        console.log(error);
      });
    </script>
  </body>
</html>

Async Await Example

<html>
  ...
  <body>
    <div id="cardNumber" paysafe="card-number"></div>
    <div id="cvv" paysafe="cvv"></div>
    <div id="expiryDate" paysafe="expiry-date"></div>
    <script>
      initializeJs();

      async function initializeJs() {
        try {
              const hostedFieldInstance = await paysafe.fields.setup("my Base64 encoded single-use-token API key", options);
              const paymentMethods = await hostedFieldInstance.show();

              if (paymentMethods.card && !paymentMethods.card.error) {
                hostedFieldInstance.on("Submit", function(instance, event) {
            document.getElementById("pay-button").disabled = instance.areAllFieldsValid();
          });
              }
        } catch (error) {
              console.log(error);
        }
      }
    </script>
  </body>
</html>

The supported instance events are listed below:

Event Description

CardBrandRecognition

The card brand is recognized from the card number entered.
Submit The customer pressed "Enter" while one of the fields is focused.
BadBin The card brand is enabled for transaction salvage and there is a chance that the transaction will be declined
UnsupportedCardBrand The card brand is not configured for the merchant's account

Callback

The callback function has the following signature

function callback(instance, event) {
  ...
}

The function signature contains the following parameters:

Parameter Required Type Description

instance

true object Paysafe.js instance in which the event occurred.
event true object Information about the event.
event
type true string Type/name of the event.
target true object The Paysafe.js field element that caused the event.
data true object Information about the field state.
target
fieldName true string Field name of the Paysafe.js field element.
containerElement true HTMLElement HTML container of the iframe.
data
isEmpty true boolean true if the field value is empty.
cardBrand true string

Type of the card if recognized, or undefined if not

Supported card types:

  • American Express
  • Mastercard
  • Visa
  • Diners Club
  • JCB
  • Maestro
declineRate true number The chance of bank decline of this particular brand in percentage
salvageFlow true boolean whether the salvage flow is above the configured threshold for the merchant
{return} false any No specific behavior associated with the return value.
{context} true HTMLElement The iframe container of the field in which the event occurred.

List of errors thrown on registering for events:

Code Display Message Detailed Message Description

9005

There was an error (9005), please contact our support. Events should be string. The supplied events parameter is not a string.
9008 There was an error (9008), please contact our support. Missing events configuration. No events are specified, or events are an empty string or contain only spaces.
9009 There was an error (9009), please contact our support. Event with name ${eventName} is not supported.
9102 There was an error (9102), please contact our support. Failed to perform a BIN lookup request.
Did you find this page useful?