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 Framepay.on() method to listen for global events.

error

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

Listen to this event to detect network or configuration errors:

Framepay.initialize({
  /* configuration */
});

Framepay.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 Framepay.card.mount when FramePay is ready:

Framepay.initialize({ /* configuration */ });

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

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

token-ready

When using a digital wallet method such as Google Pay, Apple Pay or PayPal, the token data is captured by listening to the token-ready event.

For most payment methods, a token is created by calling createToken when a user submits the form. Digital wallets are express methods and do not require data from the host form. They automatically create a token after the user has completed the wallet flow, and emit a 'token-ready' event.

Framepay.on('token-ready', (token) => {
  // Token is ready to be consumed by other Rebilly APIs
});

Google Pay™ and Apple Pay methods provide a second parameter that can be used to hold additional data. For example, details of shipping information.

Framepay.on('token-ready', (token, extraData) => {
  // Access to the shipping address in here
  const { shippingDetails } = extraData;
  console.log(shippingDetails);
});

shipping-address-changed

When using Google Pay™ and Apple Pay digital wallet methods, and the shipping configuration is enabled, the shipping address data is captured by listening to the shipping-address-changed event.

The event receives the selected shipping address as the first parameter, and a function is provided as the second parameter to accept or reject the selected shipping address. Optionally, shippingOptions can be updated with new options. Also optionally, new lineItems and new amount can be provided.

const US_SHIPPING = [
  {
    id: 'free-shipping',
    label: 'Free shipping',
    description: 'Arrives in 5 to 7 days',
    amount: 0,
  },
];

const INTERNATIONAL_SHIPPING = [
  {
    id: 'international-shipping',
    label: 'International shipping',
    description: 'Arrives in 20 to 30 days',
    amount: 10,
  },
];

Framepay.on('shipping-address-changed', (shippingAddress, updateShippingOptions) => {
  if (shippingAddress.country === 'US') {
    updateShippingOptions({ status: 'success', shippingOptions: US_SHIPPING });
  } else {
    updateShippingOptions({
      status: 'success',
      shippingOptions: INTERNATIONAL_SHIPPING,
      lineItems: [
        {
          label: 'Shipping',
          amount: shippingOption.amount,
        },
        {
          label: 'Tax',
          amount: '10.99',
        },
      ],
      amount: calculateNewTotalAmount(),
    });
  }
});

If you do not ship to the given location, provide an unsuccessful response.

const US_SHIPPING = [
  {
    id: 'free-shipping',
    label: 'Free shipping',
    description: 'Arrives in 5 to 7 days',
    amount: 0,
  },
];

const INTERNATIONAL_SHIPPING = [
  {
    id: 'international-shipping',
    label: 'International shipping',
    description: 'Arrives in 20 to 30 days',
    amount: 10,
  },
];

Framepay.on('shipping-address-changed', (shippingAddress, updateShippingOptions) => {
  if (shippingAddress.country === 'US') {
    updateShippingOptions({ status: 'fail' });
    /**
     * Optional details
     * updateShippingOptions({ status: 'fail', details: { reason: 'NO_SHIPPING', message: 'Do not have shipping provider' } });
     */
  } else {
    updateShippingOptions({ status: 'success', shippingOptions: INTERNATIONAL_SHIPPING });
  }
});

For more information, see Apple Pay reference, and Google Pay reference.

shipping-option-changed

When using Google Pay™ and Apple Pay digital wallet methods, and the shipping configuration is enabled with shipping method options, selected shipping option data is captured by listening to the shipping-option-changed event.

The event receives the selected shipping option as the first parameter, and a function is provided as the second parameter to update the transaction amount and optionally the line items.

Framepay.on('shipping-option-changed', (shippingOption, updateTransaction) => {
  // Update the total amount based on the new shipping cost
  updateTransaction({
    amount: calculateNewTotalAmount(shippingOption),
    lineItems: [
      {
        label: 'Shipping',
        amount: shippingOption.amount,
      },
      {
        label: 'Tax',
        amount: '10.99',
      },
    ],
  });
});

billing-address-changed

When using the Apple Pay digital wallet method, to capture the billing address before authorizing the transaction, listen to the billing-address-changed event.

The event receives the captured billing contact as the first parameter, and a function as the second parameter to update the transaction amount and, optionally, the line items.

Google Pay™ does not reveal the billing address information before authorizing the transaction.

For more information, see Apple Pay reference

Framepay.on('billing-address-changed', (billingContact, updateTransaction) => {
  // Update the total amount based on the new shipping cost
  updateTransaction({
    amount: calculateNewTotalAmount(billingContact),
    lineItems: [
      {
        label: 'E-book',
        amount: '29.99',
      },
      {
        label: 'Tax',
        amount: '7.99',
      },
    ],
  });
});

Element events

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:

const card = Framepay.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:

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:

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

change

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

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

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, and CVV are correct.

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

Framepay.on('ready', function () {
  const card = Framepay.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.

const card = Framepay.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.