Last updated
These docs are intended for a developer audience.Dismiss

Reference

RebillyInstruments.mount()

Use this method to mount the library UI components to the DOM of your website, and configure the experience for all your payment instrument methods. This method returns a Promise and accepts a single configuration object.

await RebillyInstruments.mount({ /* organizationId, publishableKey, websiteId, form, items */ });

Mount options

OptionTypeValueDescription
organizationIdstringRequired

Your organization ID.

publishableKeystringRequired

Your publishable API key.

websiteIdstringRequired

Your website ID.

itemsarray<object>
Requires one of: items money invoiceId transactionId

The list of plan items to be used for the transaction.

items[]object
Required with: items

Properties: planId quantity thumbnail
items[].planIdstring
Required with: items[]

Rebilly planId for the item.

items[].quantitynumber|object
Required with: items[]

Number of this item being purchased.

items[].quantity.defaultnumber

Number of this item being purchased. If minimum, maximum or multipleOf values are specified, the quantity field becomes editable.

items[].quantity.minimumnumber1

Specifies the minimum number of this item that can be purchased.

items[].quantity.maximumnumberNumber.MAX_SAFE_INTEGER

Specifies the maximum number of this item that can be purchased.

items[].quantity.multipleOfnumber1

The number by which the quantity of this item can be changed.

items[].thumbnailstring

Image source for the item. Recommend ~100px by 100px.

addonsarray<object>
Requires one of: addons

The list of add-ons items to be used for the transaction. Requires items.

addons[]object
Required with: addons

Properties: planId quantity thumbnail
addons[].planIdstring
Required with: addons[]

Rebilly planId for the addon.

addons[].quantitynumber
Required with: addons[]

Number of this addon being purchased.

addons[].thumbnailstring

Image source for the addon. Recommend ~100px by 100px.

bumpOfferarray<object>
Requires one of: bumpOffer

List of bump offer items to be used for the transaction instead of items. Requires items.

bumpOffer[]object
Required with: bumpOffer

Properties: planId quantity thumbnail
bumpOffer[].planIdstring
Required with: bumpOffer[]

Rebilly planId for the bump offer.

bumpOffer[].quantitynumber
Required with: bumpOffer[]

Number of this bump offer being purchased.

bumpOffer[].thumbnailstring

Image source for the bump offer. Recommend ~100px by 100px.

moneyobject
Requires one of: items money invoiceId transactionId

Properties: amount currency
money.amountnumber
Required with: money

The transaction amount. For example, "9.99" or 5.

money.currencystring
Required with: money
invoiceIdstring
Requires one of: items money invoiceId transactionId

ID of a Rebilly invoice. Requires a jwt.

transactionIdstring
Requires one of: items money invoiceId transactionId

ID of a Rebilly transaction. Requires a jwt.

payoutobject
Requires one of: payoutRequestId

Payout configurations. Requires a jwt.

payout.payoutRequestIdstring

ID of the payout request.

depositobject
Requires one of: depositRequestId currency
deposit.depositRequestIdstring

ID of the deposit request.

deposit.currencystring
deposit.amountnumber

Default deposit amount. For example, 9.99 or 5.

deposit.buttonsarray<number>null

Displays buttons for the quick selection of deposit amounts.

deposit.editablebooleantrue

Specifies whether the customer can enter a deposit amount into a text input field. If this vale is false, the customer may still change the deposit amount if deposit.buttons are provided.

deposit.customAmountobject

Validation of allowed deposit amount values.

deposit.customAmount.minimumnumber1

Minimum allowed deposit amount.

deposit.customAmount.maximumnumber1000000000000

Maximum allow deposit amount.

formstring|HTMLElement.rebilly-instrumentsRequired

CSS class or HTML element where the form mounts.

summarystring|HTMLElement.rebilly-instruments-summary

CSS class or HTML element where the summary mounts.

jwtstring
Required with: invoiceId transactionId

An exchanged token for customer authorization to the invoice or transaction resource.

apiModestringlive

Rebilly environment.


Allowed values: live sandbox
transactionTypestringpurchase

When set to setup, the payment instrument will be available for future transactions.


Allowed values: purchase setup
cssstringnull

A stringified CSS that overrides default styling.

themeobjectnull

Customizes the appearance of Rebilly instruments.

theme.colorPrimarystring#0044d4

Primary theme color (CSS value).

theme.colorBackgroundstring#FFFFFF

Background color (CSS value).

theme.colorTextstring#0D2B3E

Main font color (CSS value).

theme.colorDangerstring#CD5C5C

Error message text color (CSS value).

theme.borderRadiusstring4px

General border radius (in px).

theme.labelsstringstacked

Changes the layout and behavior of the label inputs.


Allowed values: floating stacked
Theme properties for font
Theme properties for heading
Theme properties for button
Theme properties for button hover state
Theme properties for button active state
Theme properties for input
Theme properties for input hover state
Theme properties for input focus state
Theme properties for input's placeholder
Theme properties for input selected text
Theme properties for invalid input
Theme properties for invalid input hover state
Theme properties for invalid input focus state
Theme properties for invalid input's placeholder
Theme properties for invalid input selected text
i18nobjectnull

Configurable object to override translations and texts.


Properties: en (or any country ISO code like "en-CA")
i18n[countryISOCode]objectnull

Language specific translations.


Properties: summary form confirmation result validations paymentMethods
i18n[countryISOCode].summaryobjectnull

Summary related fields.


Properties: subTotal discounts taxes shipping total
i18n[countryISOCode].formobjectnull

Form related fields.


Properties: expressCheckout or continue bumpOffer billingAddressTitle address useSameAsBillingAddress shippingAddressTitle paymentCard ach
i18n[countryISOCode].form.achobjectnull

Payment card form related fields.


Properties: addNew useExisting accountingNumber routingNumber iban
i18n[countryISOCode].form.paymentCardobjectnull

Payment card form related fields.


Properties: addNew useExisting
i18n[countryISOCode].form.bumpOfferobjectnull

Bump offer related fields.


Properties: title startingAt
i18n[countryISOCode].confirmationobjectnull

Confirmation related fields.


Properties: billingAddressTitle shippingAddressTitle paymentMethodTitle addons edit confirm goBack sameAsBillingAddress addressFromPayPal paymentMethodTitle save cancel
i18n[countryISOCode].confirmation.addonsobjectnull

Add-ons related fields.


Properties: title startingAt
i18n[countryISOCode].resultobjectnull

Result related fields.


Properties: success failure wrong
i18n[countryISOCode].validationsobjectnull

Validation related fields.


Properties: form
i18n[countryISOCode].validationsobjectnull

Validation related fields.


Properties: form
i18n[countryISOCode].validations.addressobjectnull

Form validation related fields.


Properties: firstName lastName fullName email address address city country region state province postalCode zipCode
i18n[countryISOCode].validations.confirmationobjectnull

Confirmation validation related fields.


Properties: deliveryAddress
i18n[countryISOCode].paymentMethodsobjectnull

Change the display name of different payment methods.


Properties: payment-card ach
countryCodestringUS

Country code for the transaction.

localestringauto

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


Allowed values: en es
paymentInstrumentsobject

Configurations for payment instruments


Properties: address additionalFields compactExpressInstruments googlePay paymentCard allowCreate allowDeactivate allowMakeDefault allowUpdate
paymentInstruments.compactExpressInstrumentsbooleanfalse

Display express payment instrument methods as inline pill buttons, or list of full width button.

paymentInstruments.allowCreatebooleantrue

Display button to allow the creation of a new payment instrument.

paymentInstruments.allowDeactivatebooleanfalse

Display option on selected payment instruments to deactivate the payment instrument.

paymentInstruments.allowMakeDefaultbooleanfalse

Display option on a selected payment instrument to mark it as the customer's default payment instrument.

paymentInstruments.allowUpdatebooleanfalse

Display options on a selected payment instrument to update the details of the payment instrument.

paymentInstruments.addressobject

Configure how address forms look and behave across the library

paymentInstruments.address.namestringdefault

Controls how the first name and last name inputs are displayed.


Properties: default combined stacked
paymentInstruments.address.regionstringdefault

Controls how the country, region, and postalCode inputs are displayed.


Properties: default split stacked
paymentInstruments.address.showarray<string>

Controls if of the listed inputs are displayed.


Properties: all email organization phoneNumber city country region postalCode
paymentInstruments.address.hidearray<string>

Controls if any of the listed inputs are not displayed.


Properties: all address address2
paymentInstruments.address.requirearray<string>

Controls if any of the listed inputs are required to be filled. Note: firstName and lastName are always required. country is required if there are shippable plans in the items.


Properties: organization email phoneNumber address address2 city country region postalCode
paymentInstruments.paymentCardobject

Payment card configuration options.


Properties: input
paymentInstruments.paymentCard.inputstringdefault

Controls if payment card inputs are split apart. Default is to combine the inputs.


Properties: default split
paymentInstruments.googlePayobject

Google Pay configuration options.


Properties: displayOptions
paymentInstruments.googlePay.displayOptionsobject

Google Pay display options.


Properties: buttonColor buttonHeight buttonType
paymentInstruments.additionalFieldsobject

Display options for additional fields.


Properties: show require
paymentInstruments.additionalFields.showarray<string>

Controls whether any of the listed inputs are displayed.


Properties: poNumber
paymentInstruments.additionalFields.requirearray<string>

Controls whether any of the listed inputs are required to be filled.


Properties: poNumber
featuresobject

Controls features related to the UI flow.


Properties: hideConfirmation hideResult showCoupons enableTelemetry
features.hideConfirmationbooleanfalse

Displays the confirmation screen. Enable this to build your own confirmation screen.

features.hideResultbooleanfalse

Displays the result screen. Enable this to build your own result screen.

features.hideContinuebooleanfalse

Displays a continue button. Enable this option to stop customers from proceeding through the payment flow.

features.showCouponsarray<string>null

Enable and display coupons within summary details. Use array values to set coupon display locations.


Properties: summary confirmation
features.enableTelemetrybooleantrue

Enable this option to allow Rebilly to access data on Rebilly Instruments library usage. Disable this option to not provide any data on Rebilly Instruments library usage.

features.hideZeroAmountSummaryItemsbooleanfalse

Enable this option to hide any invoice items with a price of 0.

Example

Payment methods that are displayed in payment forms are based on the gateway configuration. For more information, see Set up a payment gateway.

RebillyInstruments.mount({
  organizationId: "abc-123-xyz",
  publishableKey: "pk_sandbox_1234567890",
  websiteId: "ghi-789-qst",
  form: ".rebilly-instruments",
  summary: ".rebilly-instruments-summary",
  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"
    }, {
        planId: "abc-567-xyz",
        quantity: {
            default: 1,
            multipleOf: 1,
            minimum: 1,
            maximum: 20
        }
    }
  ],
  addons: [
    {
      planId: "fgh-123-uio",
      quantity: 1,
      thumbnail: "https://www.example.com/picture-3.png"
    }, {
      planId: "vbn-987-jkl",
      quantity: 2,
      thumbnail: "https://www.example.com/picture-4.png"
    }
  ],
  bumpOffer: [
    {
      planId: "kjh-123-edw",
      quantity: 1,
      thumbnail: "https://www.example.com/picture-5.png"
    }, {
      planId: "hyu-543-klo",
      quantity: 1,
      thumbnail: "https://www.example.com/picture-6.png"
    }
  ],
  apiMode: "sandbox",
  css: `
    .rebilly-instruments-summary-line-item-figure {
      border: 2px solid #0044d4;
    }
  `,
  theme: {
    colorPrimary: "#0044d4",
    colorDanger: "#cd5c5c",
    colorText: "#0d2b3e",
    colorBackground: "#ffffff",
    buttonColorText: "#ffffff",
    fontFamily: "Comic Sans MS",
    labels: "floating"
  },
  i18n: {
    en: {
      summary: {
        subTotal: "Sub Total",
        discounts: "Discounts",
        taxes: "Taxes",
        shipping: "Shipping",
        total: "Total"
      },
      form: {
        expressCheckout: "Express checkout",
        or: "Or",
        popupOverlayText: "Press here to show popup window",
        "continue": "Continue",
        bumpOffer: {
          title: "Yes, I want to upgrade!",
          startingAt: "Starting at {basePrice}"
        },
        billingAddressTitle: "Billing address",
        useSameAsBillingAddress: "Use same billing address for shipping",
        shippingAddressTitle: "Shipping address",
        address: {
          organizationLabel: "Organization",
          organizationPlaceholder: "My Organization Name",
          firstNameLabel: "First Name",
          firstNamePlaceholder: "John",
          lastNameLabel: "Last Name",
          lastNamePlaceholder: "Doe",
          fullNameLabel: "Full Name",
          fullNamePlaceholder: "John Doe",
          emailLabel: "Email",
          emailPlaceholder: "person@example.com",
          phoneNumberLabel: "Phone number",
          phoneNumberPlaceholder: "",
          addressLabel: "Address",
          addressPlaceholder: "",
          address2Label: "Address 2",
          address2Placeholder: "",
          cityLabel: "City",
          cityPlaceholder: "",
          countryLabel: "Country",
          countryPlaceholder: "",
          regionLabel: "Region",
          regionPlaceholder: "",
          stateLabel: "State",
          statePlaceholder: "",
          provinceLabel: "Province",
          provincePlaceholder: "",
          postalCodeLabel: "Postal code",
          postalCodePlaceholder: "",
          zipCodeLabel: "Zip code",
          zipCodePlaceholder: ""
        }
      },
      confirmation: {
        billingAddressTitle: "Billing address",
        shippingAddressTitle: "Shipping address",
        paymentMethodTitle: "Payment method",
        edit: "Edit",
        confirm: "Confirm",
        goBack: "Choose another payment method",
        addons: {
          title: "Other customers also selected",
          startingAt: "Starting at {basePrice}"
        }
      },
      result: {
        success: "Thank you for your purchase!",
        failure: "Transaction {result}",
        wrong: "Something went wrong"
      },
      validations: {
        address: {
          firstName: {
            required: "First name is required."
          },
          lastName: {
            required: "Last name is required."
          },
          fullName: {
            required: "Full name is required.",
            lastNameMissing: "Must include first name and last name."
          },
          email: {
            required: "Email is required.",
            validEmail: "Email must be a valid email address."
          },
          address: {
            required: "Address is required."
          },
          address2: {
            required: "Address 2 is required."
          },
          city: {
            required: "City is required.",
            noSpecialCharacters: "City cannot have any special characters."
          },
          country: {
            required: "Country is required."
          },
          region: {
            required: "Region is required."
          },
          state: {
            required: "State is required."
          },
          province: {
            required: "Province is required."
          },
          postalCode: {
            required: "Postal code is required.",
            maxLength: "Postal code cannot have more than 10 characters."
          },
          zipCode: {
            required: "Zip code is required.",
            maxLength: "Zip code cannot have more than 10 characters."
          }
        }
      }
    }
  },
  countryCode: "US",
  locale: "auto",
  paymentInstruments: {
    compactExpressInstruments: true,
    allowDeactivate: false,
    allowUpdate: false,
    allowMakeDefault: false,
    allowCreate: true,
    enableTelemetry: true,
    address: {
      name: "default",
      region: "default",
      show: ["organization", "phoneNumber"],
      hide: [],
      require: ["address"]
    },
    googlePay: {
      displayOptions: {
        buttonColor: "black",
        buttonHeight: "48px",
        buttonType: "plain"
      }
    }
  },
  features: {
    hideConfirmation: false,
    hideResult: false,
    hideContinue: false,
    showCoupons: ["summary", "confirmation"],
    hideZeroAmountSummaryItems: false
  }
});

RebillyInstruments.on()

Rebilly Instruments supports 3 events:

  • instrument-ready
  • purchase-completed
  • setup-completed

RebillyInstruments.on("instrument-ready")

The instrument-ready event will be called once the payment instrument token is generated.

RebillyInstruments.on("instrument-ready", (instrument) => {
  console.info("instrument-ready", instrument);
});

RebillyInstruments.on("purchase-completed")

The purchase-completed event will be called once the transaction is processed.

RebillyInstruments.on("purchase-completed", (transaction) => {
  console.info("purchase-completed", transaction);
});

RebillyInstruments.on("setup-completed")

The setup-completed event is called once the payment instrument is processed.

RebillyInstruments.on("setup-completed", (setup) => {
  console.info("setup-completed", setup);
});

RebillyInstruments.show()

This method will display the following UI elements:

  • Confirmation
  • Result

By default the library will display these screens, use the mount options options.features.hideConfirmation and options.features.hideResult to disable them. Use this function in conjunction with RebillyInstruments.on to display the screens that provides the right argument.

RebillyInstruments.show("confirmation")

Displays the confirmation screen after the instrument-ready event is triggered. If this value is set to false, you must trigger the purchase manually .

RebillyInstruments.show("confirmation", instrument);

RebillyInstruments.show("result")

Displays the result of a transaction after the purchase-completed event is triggered. If this value is set to false, you must trigger purchase the manually.

RebillyInstruments.show("result", transaction);

RebillyInstruments.purchase()

Initializes the purchase by passing the instrument data from the instrument-ready event. If the mount options.features.hideConfirmation option is set to true, this method must be triggered by a user click event in the browser.

RebillyInstruments.purchase(instrument);

RebillyInstruments.setup()

Initializes the process to make a payment instrument available for future use. Requires that instrument data is passed from the instrument-ready event. If mount the options.features.hideConfirmation option is set to true, this instrument must be triggered by a user click event in the browser.

RebillyInstruments.setup(instrument);

RebillyInstruments.update()

Updates the library information or styles. All mount options are updatable.

RebillyInstruments.update(options);

RebillyInstruments.destroy()

Destroys the library instance.

RebillyInstruments.destroy();

RebillyInstruments.version

Returns the version of the library.

console.log(RebillyInstruments.version); // RebillyInstruments Ver.X