@rebilly/framepay

A lightweight wrapper to load Rebilly's FramePay library and provide types.

Why use @rebilly/framepay?

FramePay must be loaded from our CDN, by adding a script tag to your webpage, for example:

<html>
  <head>
    <link href="https://framepay.rebilly.com/framepay.css" rel="stylesheet" />
    <script src="https://framepay.rebilly.com/framepay.js"></script>
  </head>
  <body></body>
</html>

But this can be difficult to implement in a modern web application in a non-blocking way, and cannot provide types for typescript applications.

This library provides:

🔄 Async script loading to ensure page rendering isn't blocked
⚡️ A Promise API to know when script loading is complete
🛠 TypeScript support out of the box

Installation

npm install @rebilly/framepay
# or
yarn add @rebilly/framepay

Usage

The package exports a loadFramepay function that loads the FramePay CDN script and CSS. It returns a promise that resolves with the FramePay instance.

Basic Usage

import { loadFramepay } from '@rebilly/framepay';

try {
  const framepay = await loadFramepay();

  // Use FramePay as normal.
  // For complete examples, see: https://www.rebilly.com/docs/dev-docs/basic-setup
  framepay.initialize({
    publishableKey: 'your-publishable-key',
    // Additional configuration parameters
  });
  framepay.on('error', function (error) {
    console.error('FramePay error:', error);
  });
  framepay.on('ready', function () {
    // Your page should have a DOM element with the id "card-element"
    framepay.card.mount('#card-element');
  });
} catch (error) {
  console.error('Failed to load Framepay: ', error);
}

TypeScript Support

This package includes TypeScript declarations for FramePay.

For example:

import type { FramePay, CardElement } from '@rebilly/framepay';

const mountCard = (framepay: FramePay, elementId: string): CardElement => {
  return framepay.card.mount(elementId);
};

Custom Script/Style URLs

You can optionally specify custom URLs for the FramePay script and stylesheet:

const framepay = await loadFramepay({
  scriptLink: 'https://custom-domain.com/framepay.js',
  styleLink: 'https://custom-domain.com/framepay.css',
});

Global Window Object

When FramePay is loaded, it automatically adds itself to the global window object. This means you can also access FramePay directly through these global variables:

const framepay = await loadFramepay();

// After loading, you can access FramePay as a global variable:
window.Framepay.initialize({
  // ...
});