1. Installation and Setup
To use the widget, add a <script> import in the header of the main index.html file.
Set up the correct <meta> tag for viewports in the header of the same file to view the widget.
JavaScript
To integrate the CCBill API Payment Widget into your JavaScript application, complete the following steps:
2. Usage
Create a placeholder <div> with an ID in the body of the index.html file to add the widget. The <div> will be used to append the widget dynamically from a JavaScript file (app.js).
Add an additional <script> tag pointing to the app.js file. The file contains widget configuration and initialization.
Currently, the application is consuming the widget but has no configuration yet.
To initialize the widget, do the following in the app.js file:
1. Add the required parameter constants and their values.
2. Set the required attributes on the widget.
3. Lastly, append the widget to the placeholder <div> created earlier.
Attributes
| PARAMETER | ||
|---|---|---|
| apiKey | string | |
| A valid OAuth token generated using the merchant application ID and the secret key asigned to the client account involved in the transaction. | ||
| clientAccount | string | |
| Merchant account number. The value must be in the range between 900000 and 999999. |
||
| subAccount | string | |
| Merchant subaccount number. The value must be in the range between 0 and 9999. |
||
| currency | string | |
| Currency used for this transaction. Accepted values: USD / GBP / EUR / CAD / AUD / JPY |
||
| initialPrice | string | |
| This is the initial transaction price. Formatted as a float value up to 2 decimal points, e.g., 5.00 |
||
| initialPeriod | string | |
| The length (in days) of the initial billing. Formatted as an integer value, e.g., 5 NOTE: Set to 0 in case of a single and non-recurring transaction. |
||
| PARAMETER | ||
|---|---|---|
| language | string | |
| The language the widget will be rendered in. Accepted values: en / es / fr / de / it / ja / ko / zh_tw / zh_cn / pt_br / hi / sv / da / no / nl NOTE: If the language is not supplied or the supplied language is not supported, the widget will try to determine the language from the browser. If that language is not supported, it will default to English. |
||
| theme | string | |
| The theme the widget will be loaded in. Accepted values are ccb-light and ccb-dark NOTE: If the value is not supplied or is invalid, the system will default to ccb-light. Custom themes are possible; please refer to the theming documentation. |
||
| description | string | |
| Optional product description to show in the widget. Up to 500 characters (no HTML/images allowed). |
||
| lifeTimeSubscription | string | |
| Indicates whether the transaction is a lifetime subscription or not. Formatted as boolean value 1 or 0 |
||
| rebills | string | |
| Represents a recurring transaction, rebilling the consumer X times according to the value set. Formatted as an integer value 1 to 99 ("99" being indefinite). NOTE: When rebills is provided recurringPrice and recurringPeriod become required fields |
||
| recurringPrice | string | |
| The recurring price in case of a recurring transaction. Formatted as a float value up to 2 decimal points, e.g., 5.00 It is a required parameter for recurring transactions. |
||
| recurringPeriod | string | |
| The recurring period in case of a recurring transaction. Formatted as an integer value, e.g., 5 |
||
Depending on whether the passed parameters are correct, different screens appear.
If all the passed parameters are correct, the following screen appears:
In case of a misconfiguration or if one of the values passed in is not valid, the following screen is displayed:
3. Create Payment Token
This step shows how a filled-out and submitted form generates a payment token, which is required to send a charge request:
Pressing the Place your order button generates a payment token, which passes into the application as a CustomEvent.
To get the data from the widget and use it in an application, add an event listener for a custom event called tokenCreated, which will give you data in the details property.
Creating a charge with this payment token will require adding the customer's IP address as an additional payload (ipAddress) or header (X-Origin-IP) parameter.
4. Customize CSS (Optional)
Customize the appearance of the CCBill API Payment Widget through a preset Theme or with CSS variables to modify its appearance.
With CSS variables, the widget easily adapts to match the look and feel of a website. This guide will walk you through the customization process, including preset dark and light themes.
Setting the Viewport Meta Tag
The viewport meta tag sets the initial viewport properties for a web page. It helps control how the web page displays on various devices, ensuring the content fits and scales appropriately.
This is crucial for responsive web design and providing a good user experience on different screen sizes and orientations.
You can set up the correct <meta> tag for viewports in the header of the main index.html file.
Preset Light and Dark Themes
The dark or light themes are standard themes with which the widget is shipped. These themes are ready to use as-is without any additional customization.
Define the constant and its value in the app.js file using ccb-dark or ccb-light as values.
Add the theme widget attribute to pass the information to the widget.
Available CSS Variables
To customize the theme further you must link your CSS stylesheet in the index.html file.
You can customize various aspects of the widget using the following CSS variables:
| Element | Variable |
|---|---|
| Widget Background | --ccb-background |
| Element | Variable |
|---|---|
| Ribbon - Language Dropdown | |
| Background | --ccb-ribbon-background |
| List - Background | --ccb-language-dropdown-background |
| Text | --ccb-language-dropdown-text |
| Icon - Chevron | --ccb-language-dropdown-icon |
| Header - Price / Product Description | |
| Background | --ccb-header-background |
| Section Divider - Border | --ccb-section-divider-border |
| Price - Text | --ccb-header-price-text |
| Description - Text | --ccb-header-description-text |
| Header - Currency Code - Text | --ccb-header-currency-code-text |
| Section Headers | |
| Header Text | --ccb-section-header |
| Input Field and Dropdown | |
| Background | --ccb-input-field-background |
| Placeholder Text | --ccb-input-field-placeholder |
| Text | --ccb-input-field-text |
| Border | --ccb-input-field-border |
| Border - In Focus | --ccb-input-field-border-infocus |
| Dropdown Country - Divider | --ccb-country-dropdown-divider |
| Dropdown Language - Background | --ccb-language-dropdown-background |
| Links | |
| Text | --ccb-link |
| Text - Hover | --ccb-link-hover |
| Text - Visited | --ccb-link-visited |
| Terms & Conditions | |
| Text | --ccb-terms-and-conditions-text |
| Call to Action - Place your Order Button | |
| Background | --ccb-cta-background |
| Background - Hover | --ccb-cta-background-hover |
| Background - Action | --ccb-cta-background-action |
| Text | --ccb-cta-text-color |
| Text - Hover | --ccb-cta-text-color-hover |
| Footer | |
| Background | --ccb-footer-background |
| Text | --ccb-footer-text |
| Border | --ccb-validation-border |
| Input Field Text | --ccb-validation-text |
| Error Message Text | --ccb-validation-error-text |
| Background | --ccb-validation-background |
| Element | Variable |
|---|---|
| Border | |
| Input Field Text | --ccb-validation-text |
| Error Message Text | --ccb-validation-error-text |
| Background | --ccb-validation-background |
Feel free to modify these variables according to your website's color scheme and design preferences. Experiment with different values to achieve the desired look for your payment widget.