@rebilly/instruments

Rebilly Instruments

The last payment integration that you will ever need.

Rebilly Instruments is in active development and should be treated as beta software. This means it may contain bugs and instability.

Getting Started

⏳ Installation

Install Rebilly Instruments with this Quickstart command to add Rebilly instruments to your existing project:

(Use yarn to install (recommended). Install yarn with these docs.)

yarn add @rebilly/instruments

or

• (Use npm/npx to install Rebilly Instruments.)

npx install @rebilly.instruments

Enjoy 🎉

🛠️ Usage

<div class="rebilly-instruments-summary"></div>
<div class="rebilly-instruments"></div>

<script type="text/javascript">
  import RebillyInstruments from '@rebilly/instruments';

  RebillyInstruments.initialize({
    // ...see documentation below for initialize options
  });

  RebillyInstruments.mount({
    // ...see documentation below for mounting options
  });
</script>

Initialization Options

organizationId

Required string

The Rebilly organization id that all api requests will be associated with.

publishableKey

Required string

The Rebilly publishable api key used to access the storefront api's.

websiteID

Required string

The Rebilly website api.

apiMode

string - default: "live". "live", "sandbox"

The rebilly storefront api mode

css

string - default: null.

A stringified css to be injected into the forms to override default styling

theme

object - default: null

Configurable object to override some styling. Use alone or with css to control the styles.

{
  typography: {/* options */},
  color: {/* options */}
}

typography

• fontFamily: Same as CSS property "font-family". Will be used thoughout the library ui

color

• primary: CSS hexcode or color name, used to draw user attention
• errorText: CSS hexcode or color name, used to display error messages
• text: CSS hexcode or color name, used to display font color
• buttonText: CSS hexcode or color name, used for buttons text, primary will be it's background
• background: CSS hexcode or color name, the color used for the background of the forms

i18n

object - default: null

{
  en: {
    /* translations */
  },
  "en-US": {
    /* translations */
  },
  // any other languages...
}

Example Initialization Options

{
  organizationId: "abc-123-xyz",
  publishableKey: "def-456-uvw",
  websiteId: "ghi-789-qst",
  apiMode: "sandbox",
  css: ".rebilly-instruments-summary-line-item-figure { border: 2px solid #0044d4; }",
  theme: {
    color: {
      primary: "#0044d4",
      errorText: "#cd5c5c",
      text: "#0D2B3E",
      buttonText: "#ffffff",
      background: "#ffffff"
    },
    typography: {
      fontFamily: "Comic Sans MS"
    }
  },
  i18n: {
    en: {
      confirmation: {
        confirm: "Please continue to purchase"
      }
    }
  }
}

Mount Options

form

string or HTMLElement - default: ".rebilly-instruments"

The CSS class or HTML element were the form will be mounted

summary

string or HTMLElement - default: ".rebilly-instruments-summary"

The CSS class or HTML element were the summary will be mounted.

options

object

The configurations that are to be passed to the library for use.

{
  local: ''
  features: {},
  intent: {},
  paymentInstruments: {},
}

local

string - default: "auto"

The locale of the forms to be posted, uses browser locale by default.

features

object

{
  autoConfirmation: true,
  autoResult: true
}

• autoConfirmation: default: true. Will mount the confirmation screen after instrument-ready event is triggered. Will need to trigger purchase manually if set to false. Can use RebillyInstruments.show('confirmation', options) to mount defautl component

• autoResult - default: true. Show results of transaction after purchase-complete event is triggered will need to handle purchase result manually if set to false. Can use RebillyInstruments.show('result', options) to display default component

intent

object

The information required for purchaseing or vaulting an instrument

{
  items: [],
  countryCode: 'US'
}

items

Array.objects

[{
  planId: 'abc-123-def',
  quantity: 1,
  thumbnail: 'https://www.example.com/picture.png'
}]

• planId: string - Rebilly planId for the item
• quantity: number - number of this item being purchased
• thumbnail: string - The image sorce for the item. Recommend ~100px by 100px

countryCode

string

The country code for the transaction

paymentInstruments

object

{
  compactExpressInstruments: true,
  googlePay: {}
  paymentCard: {},
}

compactExpressInstruments

boolean - default: true

Show express methods as inline pill buttons, or list of full width button.

paymentCard

object

• popup: boolean - default: false. Show method as a button with a form popup. Otherwise the form will be mounted inline.

googlePay

object

• displayOptions - display options for google pay instrument
• merchantConfig - merchant configurations for google pay instrument

displayOptions

• buttonColor - default "black". Color of google pay button. "back", "white"
• buttonType - default "short". The length of the button. "short", "long"
• buttonHeight - The value and units of the button to match other payment buttons. example: "44px", "1rem" etc.

merchantConfig

• merchantName - Google Pay merchant name
• merchantOrigin - Google Pay merchant origin

Example Mount Options

{
  form: '.form-mounting-point',
  summary: '.summary-mounting-point',
  options: {
    local: 'en-CA'
    features: {
      autoConfirmation: true,
      autoResult: true
    },
    intent: {
      items: [
        {
          planId: 'abc-123-def',
          quantity: 1,
          thumbnail: 'https://www.example.com/picture-1.png'
        }, {
          planId: 'xyz-987-uvw',
          quantity: 2,
          thumbnail: 'https://www.example.com/picture-2.png'
        }
      ],
      countryCode: 'US'
    },
    paymentInstruments: {
      compactExpressInstruments: true,
      googlePay: {
        displayOptions: {
          buttonColor: 'black',
          buttonType: 'short',
          buttonHeight: '44px'
        },
        merchantConfig: {
          merchantName: 'merchant-name',
          merchantOrigin: 'https://www.example.com'
        }
      },
      paymentCard: {
        popup: false
      },
    },
  }
}