1. Installation and Setup
To use the widget, add a <script> import in the header of the main index.html file.
To view the widget, set up the correct <meta> tag for viewports in the header of the same file.
HTML
To integrate the CCBill API Payment Widget into your Web Component application, complete the following steps:
2. Usage
This step demonstrates how to display the payment form:
Add a custom <ccb-payment-widget> tag with all required attributes and their values.
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 detail property.
For this demo, it can be done directly in the HTML file using a script tag.
Here is an example of the application getting a payment token and printing it in the console:
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 theme attribute and its value in the ccb-payment-widget tag using ccb-dark or ccb-lightas values.
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.