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
Option | Type | Value | Description |
---|---|---|---|
organizationId | string | Required Your organization ID. | |
publishableKey | string | Required Your publishable API key. | |
websiteId | string | Required Your website ID. | |
items | array<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[].planId | string | Required with: items[] Rebilly | |
items[].quantity | number|object | Required with: items[] Number of this item being purchased. | |
items[].quantity.default | number | Number of this item being purchased. If | |
items[].quantity.minimum | number | 1 | Specifies the minimum number of this item that can be purchased. |
items[].quantity.maximum | number | Number.MAX_SAFE_INTEGER | Specifies the maximum number of this item that can be purchased. |
items[].quantity.multipleOf | number | 1 | The number by which the quantity of this item can be changed. |
items[].thumbnail | string | Image source for the item. Recommend ~100px by 100px. | |
addons | array<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[].planId | string | Required with: addons[] Rebilly | |
addons[].quantity | number | Required with: addons[] Number of this addon being purchased. | |
addons[].thumbnail | string | Image source for the addon. Recommend ~100px by 100px. | |
bumpOffer | array<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[].planId | string | Required with: bumpOffer[] Rebilly | |
bumpOffer[].quantity | number | Required with: bumpOffer[] Number of this bump offer being purchased. | |
bumpOffer[].thumbnail | string | Image source for the bump offer. Recommend ~100px by 100px. | |
money | object | Requires one of: items money invoiceId transactionId Properties: amount currency | |
money.amount | number | Required with: money The transaction amount. For example, "9.99" or 5. | |
money.currency | string | Required with: money A three character ISO 4217 currency code. | |
invoiceId | string | Requires one of: items money invoiceId transactionId ID of a Rebilly invoice. Requires a | |
transactionId | string | Requires one of: items money invoiceId transactionId ID of a Rebilly transaction. Requires a | |
payout | object | Requires one of: payoutRequestId Payout configurations. Requires a | |
payout.payoutRequestId | string | ID of the payout request. | |
deposit | object | Requires one of: depositRequestId currency Deposit configurations. Requires a | |
deposit.depositRequestId | string | ID of the deposit request. | |
deposit.currency | string | Three character ISO 4217 currency code. | |
deposit.amount | number | Default deposit amount. For example, | |
deposit.buttons | array<number> | null | Displays buttons for the quick selection of deposit amounts. |
deposit.editable | boolean | true | Specifies whether the customer can enter a deposit amount into a text input field. If this vale is |
deposit.customAmount | object | Validation of allowed deposit amount values. | |
deposit.customAmount.minimum | number | 1 | Minimum allowed deposit amount. |
deposit.customAmount.maximum | number | 1000000000000 | Maximum allow deposit amount. |
form | string|HTMLElement | .rebilly-instruments | Required CSS class or HTML element where the form mounts. |
summary | string|HTMLElement | .rebilly-instruments-summary | CSS class or HTML element where the summary mounts. |
jwt | string | Required with: invoiceId transactionId An exchanged token for customer authorization to the invoice or transaction resource. | |
apiMode | string | live | Rebilly environment. Allowed values: live sandbox |
transactionType | string | purchase | When set to Allowed values: purchase setup |
css | string | null | A stringified CSS that overrides default styling. |
theme | object | null | Customizes the appearance of Rebilly instruments. |
theme.colorPrimary | string | #0044d4 | Primary theme color (CSS value). |
theme.colorBackground | string | #FFFFFF | Background color (CSS value). |
theme.colorText | string | #0D2B3E | Main font color (CSS value). |
theme.colorDanger | string | #CD5C5C | Error message text color (CSS value). |
theme.borderRadius | string | 4px | General border radius (in px). |
theme.labels | string | stacked | 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 | |||
i18n | object | null | Configurable object to override translations and texts. Properties: en (or any country ISO code like "en-CA") |
i18n[countryISOCode] | object | null | Language specific translations. Properties: summary form confirmation result validations paymentMethods |
i18n[countryISOCode].summary | object | null | Summary related fields. Properties: subTotal discounts taxes shipping total |
i18n[countryISOCode].form | object | null | Form related fields. Properties: expressCheckout or continue bumpOffer billingAddressTitle address useSameAsBillingAddress shippingAddressTitle paymentCard ach |
i18n[countryISOCode].form.ach | object | null | Payment card form related fields. Properties: addNew useExisting accountingNumber routingNumber iban |
i18n[countryISOCode].form.paymentCard | object | null | Payment card form related fields. Properties: addNew useExisting |
i18n[countryISOCode].form.bumpOffer | object | null | Bump offer related fields. Properties: title startingAt |
i18n[countryISOCode].confirmation | object | null | Confirmation related fields. Properties: billingAddressTitle shippingAddressTitle paymentMethodTitle addons edit confirm goBack sameAsBillingAddress addressFromPayPal paymentMethodTitle save cancel |
i18n[countryISOCode].confirmation.addons | object | null | Add-ons related fields. Properties: title startingAt |
i18n[countryISOCode].result | object | null | Result related fields. Properties: success failure wrong |
i18n[countryISOCode].validations | object | null | Validation related fields. Properties: form |
i18n[countryISOCode].validations | object | null | Validation related fields. Properties: form |
i18n[countryISOCode].validations.address | object | null | Form validation related fields. Properties: firstName lastName fullName email address address city country region state province postalCode zipCode |
i18n[countryISOCode].validations.confirmation | object | null | Confirmation validation related fields. Properties: deliveryAddress |
i18n[countryISOCode].paymentMethods | object | null | Change the display name of different payment methods. Properties: payment-card ach |
countryCode | string | US | Country code for the transaction. |
locale | string | auto | Locale of the forms to be posted, uses browser locale by default. Allowed values: en es |
paymentInstruments | object | Configurations for payment instruments Properties: address additionalFields compactExpressInstruments googlePay paymentCard allowCreate allowDeactivate allowMakeDefault allowUpdate | |
paymentInstruments.compactExpressInstruments | boolean | false | Display express payment instrument methods as inline pill buttons, or list of full width button. |
paymentInstruments.allowCreate | boolean | true | Display button to allow the creation of a new payment instrument. |
paymentInstruments.allowDeactivate | boolean | false | Display option on selected payment instruments to deactivate the payment instrument. |
paymentInstruments.allowMakeDefault | boolean | false | Display option on a selected payment instrument to mark it as the customer's default payment instrument. |
paymentInstruments.allowUpdate | boolean | false | Display options on a selected payment instrument to update the details of the payment instrument. |
paymentInstruments.address | object | Configure how address forms look and behave across the library | |
paymentInstruments.address.name | string | default | Controls how the first name and last name inputs are displayed. Properties: default combined stacked |
paymentInstruments.address.region | string | default | Controls how the Properties: default split stacked |
paymentInstruments.address.show | array<string> | Controls if of the listed inputs are displayed. Properties: all email organization phoneNumber city country region postalCode | |
paymentInstruments.address.hide | array<string> | Controls if any of the listed inputs are not displayed. Properties: all address address2 | |
paymentInstruments.address.require | array<string> | Controls if any of the listed inputs are required to be filled. Note: Properties: organization email phoneNumber address address2 city country region postalCode | |
paymentInstruments.paymentCard | object | Payment card configuration options. Properties: input | |
paymentInstruments.paymentCard.input | string | default | Controls if payment card inputs are split apart. Default is to combine the inputs. Properties: default split |
paymentInstruments.googlePay | object | Google Pay configuration options. Properties: displayOptions | |
paymentInstruments.googlePay.displayOptions | object | Google Pay display options. Properties: buttonColor buttonHeight buttonType | |
paymentInstruments.additionalFields | object | Display options for additional fields. Properties: show require | |
paymentInstruments.additionalFields.show | array<string> | Controls whether any of the listed inputs are displayed. Properties: poNumber | |
paymentInstruments.additionalFields.require | array<string> | Controls whether any of the listed inputs are required to be filled. Properties: poNumber | |
features | object | Controls features related to the UI flow. Properties: hideConfirmation hideResult showCoupons enableTelemetry | |
features.hideConfirmation | boolean | false | Displays the confirmation screen. Enable this to build your own confirmation screen. |
features.hideResult | boolean | false | Displays the result screen. Enable this to build your own result screen. |
features.hideContinue | boolean | false | Displays a continue button. Enable this option to stop customers from proceeding through the payment flow. |
features.showCoupons | array<string> | null | Enable and display coupons within summary details. Use array values to set coupon display locations. Properties: summary confirmation |
features.enableTelemetry | boolean | true | 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.hideZeroAmountSummaryItems | boolean | false | 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