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 aPromise
and accepts a single configuration
object.await RebillyInstruments.mount({ /* organizationId, publishableKey, websiteId, form, items */ });
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 `planId` for the item. | |
items[].quantity | number|object | Required with: items[] Number of this item being purchased. | |
items[].quantity.default | number | Number of this item being purchased. If `minimum`, `maximum` or `multipleOf` values are specified, the quantity field becomes editable. | |
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 `planId` for the addon. | |
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 `planId` for the bump offer. | |
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](https://www.iso.org/iso-4217-currency-codes.html). | |
invoiceId | string | Requires one of: items money invoiceId transactionId ID of a Rebilly invoice. Requires a `jwt`. | |
transactionId | string | Requires one of: items money invoiceId transactionId ID of a Rebilly transaction. Requires a `jwt`. | |
form | string | .rebilly-instruments | Required CSS class or HTML element where the form mounts. |
summary | string | .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 `setup`, the payment instrument will be available for future transactions. 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 |
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.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 | Properties: compactExpressInstruments googlePay paymentCard | |
paymentInstruments.compactExpressInstruments | boolean | false | Display express payment instrument methods as inline pill buttons, or list of full width button. |
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 `country`, `region`, and `postalCode` inputs are displayed. Properties: default split stacked |
paymentInstruments.address.show | arrayString | Controls if of the listed inputs are displayed. Properties: email organization phoneNumber city country region postalCode | |
paymentInstruments.address.hide | arrayString | Controls if any of the listed inputs are not displayed. Properties: address2 | |
paymentInstruments.address.require | arrayString | 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.googlePay | object | Google Pay configuration options. Properties: displayOptions | |
paymentInstruments.googlePay.displayOptions | object | Google Pay display options. Properties: buttonColor buttonHeight buttonType | |
features | object | Controls features related to the UI flow. Properties: autoConfirmation autoResult showCoupons | |
features.autoConfirmation | boolean | true | Displays the confirmation screen. Disable this to build your own confirmation screen. |
features.autoResult | boolean | true | Displays the result screen. Disable this to build your own result screen. |
features.showCoupons | array<String> | null | Enable and display coupons within summary details. Use array values to set coupon display locations. Properties: summary confirmation |
Example mount options
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: {
autoConfirmation: true,
autoResult: true,
showCoupons: ['summary', 'confirmation']
}
});
RebillyInstruments.on()
Rebilly Instruments supports 3 events:
instrument-ready
purchase-completed
setup-completed
RebillyInstruments.on('instrument-ready')
Theinstrument-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')
Thepurchase-completed
event will be called once the transaction is processed.RebillyInstruments.on('purchase-completed', (transaction) => {
console.info('purchase-completed', transaction);
});
RebillyInstruments.on('setup-completed')
Thesetup-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
options.features.autoConfirmation
and options.features.autoResult
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 theinstrument-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 thepurchase-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 theinstrument-ready
event. If the mount options.features.autoConfirmation
option is set to false
, 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 theinstrument-ready
event. If mount the options.features.autoConfirmation
option is set to false
, 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