Skip to main content

FramePay events

FramePay uses events to notify you of the state changes or errors during information processing.

Specifically, FramePay emits two categories of events:

  • global events that are used in all configurations
  • element events that are used in the 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 a 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 methods such as Google Pay, Apple Pay or PayPal, the token data is captured by listening to the token-ready event.

For most of the 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 PaymentsAI 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 can be provided.

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

const INTERNATIONAL_SHIPPING = [
  {
    id: 'international-shipping',
    label: 'International shipping',
    detail: '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',
          },
        ],
      });
    }
  }
);

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

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

const INTERNATIONAL_SHIPPING = [
  {
    id: 'international-shipping',
    label: 'International shipping',
    detail: '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: ORIGINAL_AMOUNT + shippingOption.amount,
    lineItems: [
      {
        label: 'Shipping',
        amount: shippingOption.amount,
      },
      {
        label: 'Tax',
        amount: '10.99',
      },
    ],
  });
});