Last updated

These docs are intended for a developer audience.

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
A three character [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html).
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 configurations. Requires a `jwt`.
deposit.depositRequestIdstring
ID of the deposit request.
deposit.currencystring
Three character [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html).
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].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

Properties: compactExpressInstruments googlePay paymentCard
paymentInstruments.compactExpressInstrumentsbooleanfalse
Display express payment instrument methods as inline pill buttons, or list of full width button.
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 requried. `country` is required if there are shippable plans in the items.

Properties: organization email phoneNumber address address2 city country region postalCode
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.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.

Example

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: "Discouts",
        taxes: "Taxes",
        shipping: "Shipping",
        total: "Total"
      },
      form: {
        expressCheckout: "Express checkout",
        or: "Or",
        popupOverlayText: "Click 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: "example@mail.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,
    address: {
      name: "default",
      region: "default",
      show: ["organization", "phoneNumber"],
      hide: [],
      require: ["address"]
    },
    googlePay: {
      displayOptions: {
        buttonColor: "black",
        buttonHeight: "48px",
        buttonType: "plain"
      }
    }
  },
  features: {
    hideConfirmation: false,
    hideResult: false,
    showCoupons: ["summary", "confirmation"]
  }
});

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