FramePay Events

FramePay uses events to notify state changes or errors.

Framepay emits global events that are used in all configurations, and element events that are used in payment card and bank account configurations.

Global events

Use the Rebilly.on() method to listen for global events.

error event

FramePay emits this event when there is a problem during its initialization.

Listen to this event to detect network or configuration errors:

Copy
Copied
Rebilly.initialize({ /* configuration */ });

Rebilly.on('error', (err) => {
    // err
    // {"code":"network-error","type":"error","message":"Initialization Error","details":[...]}
})

ready

After initializing FramePay, use the ready event to start mounting the element, or elements, of your selected payment methods.

For example, if you are setting up payment card method, call Rebilly.card.mount when FramePay is ready:

Copy
Copied
Rebilly.initialize({ /* configuration */ });

Rebilly.on('error', (err) => {
    ...
})

// This event won't be emitted if there are configuration errors
Rebilly.on('ready', () => {
    const card = Rebilly.card.mount('#mount-point');
})

Element events

Note

This applies only to payment card and bank account payment methods.

Payment card or bank account setups require mounting one or more elements after initialization.

For every mounted element, store it in a Javascript variable and use on() method to listen for events that are emitted when the customer interacts with the element.

For example, if you are mounting a payment card element:

Copy
Copied
const card = Rebilly.card.mount('#card');

// Use card.on(<eventType>, <handlerFunction>) to listen for element specific events

The on() method accepts two arguments:

  • eventName: String with the name of the event.
  • handler: Callback function triggered by event.

ready

Emitted by an element when the related field is loaded in the UI.

Example:

Copy
Copied
card.on('ready', function() {
    console.log('Card element is ready to use!');
});

error

Emitted by an element when there is a mount problem. For more information, see error global event.

Example:

Copy
Copied
card.on('error', function() {
    console.log('Card mount error!');
});

change

Emitted whenever the element is changed after the customer's input.

Validation

Use change event to detect validation errors in the element.

The change event handler function is the only one that receives an argument. This argument can have these properties:

Change argument property Description
source string with the type of the element where the event was emitted from.
valid Optional boolean that is present if the element contains valid data (or potentially valid data while the field is focused).
completed Optional boolean that is present if the element has valid and completed data.
error Optional object that is present if the element has invalid data. It contains these properties: {code, message, type}

Example: Use completed property from change event

Use change event to enable the submit button of your checkout form only when the combined card element is completed. That is, when pan, expiration are cvv are correct.

Copy
Copied
const button = document.getElementById('button-submit');

Rebilly.on('ready', function() {

  const card = Rebilly.card.mount('#mounting-point');

  card.on('change', function(changeData) {
    if (changeData.completed) {
      button.removeAttribute('disabled');
    } else {
      button.setAttribute('disabled', 'disabled');
    }
  });
});

Interactive example: listening for change event.

Example: Use error property from change event

Display the error messages whenever the input becomes invalid.

Copy
Copied
const card = Rebilly.card.mount('#card');

card.on('change', function(changeData) {
  ...
  if (changeData.error) {
      document.querySelector('#errors').innerText = error.message;
  }
  ...
});

focus

Emitted when the element is focused.

blur

Emitted when the element is blurred.