CCBill API Payment Widget integration guide

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.

2. Usage

Add the widget <ccb-payment-widget> element and the required parameters in the template of your component. In this example, the file is called app.vue.

Attributes

At this point, your application is consuming the widget. However, the required configuration is still missing.

Define these properties and their values in the script tag within your app.vue component file.

ValidInvalid

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

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.

When the event is caught, the onGenerateTokenId method is called with data as input, and you can use the payment token.

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.

1. Define the constant and its value in the my-app.ts file using ccb-dark or ccb-lightas values.
2. Add the theme widget attribute to pass the information to the widget.

Available CSS Variables

You can customize various aspects of the widget using the following CSS variables:

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.

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.

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

Depending on whether the passed parameters are correct, different screens appear.

ValidInvalid

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:

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.

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.

2. Usage

Add a custom <ccb-payment-widget> element and the required parameters in the typescript file of your web component. In this example, the file is called my-app.ts.
There are two ways to add the widget element to the template file:

Standard HTML Element

HTML Element with Self-closing Tags

Attributes

The Web Components application is now consuming the widget. However, the required configuration is still missing.

Define the constants and their values by adding the appropriate attributes to the widget tag in the my-app.ts template.

To provide these values to the payment widget, add the appropriate attributes to the widget tag in the render method.

Depending on whether the passed parameters are correct, different screens appear.

ValidInvalid

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.

When the event is caught, the onGenerateTokenId method is called with data as input, and you can use the payment token.

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.

1. Define the constant and its value in the my-app.ts file using ccb-dark or ccb-lightas values.

2. Add the theme widget attribute to pass the information to the payment 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:

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.

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.

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

Depending on whether the passed parameters are correct, different screens appear.

ValidInvalid

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:

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.

1. Installation and Setup

To use the widget, add a <script> import in the header of the main index.html file.

The Payment Widget HTML tag, ccb-payment-widget, is a non-standard element, and you must tell the React app to use this element:

1. Declare a global type using the declare global block.

2. Create the JSX namespace.

3. Add an IntrinsicElements interface.

4. Define a property in the interface corresponding to the element's name and specify its accepted props.

2. Usage

The React application is now aware of the custom element in the template of the App.tsx component.

There are two ways to add the widget element to the template file:

Standard HTML Element

<div> <ccb-payment-widget></ccb-payment-widget> </div>

HTML Element with Self-closing Tags

The React application is now consuming the widget. However, the required configuration is still missing.

Define the constants and their values by adding the appropriate attributes to the widget tag in the App.tsx template.

Attributes

ValidInvalid

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

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.

When the event is caught, the onGenerateTokenId method is called with data as input, and you can use the payment token.

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 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.

1. Define the constant and its value in the app.js file using ccb-dark or ccb-lightas values.

2. Add the theme widget attribute to pass the information to the Payment 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 Payment Widget using the following CSS variables:

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.

1. Installation and Setup

To use the widget, add a <script> import in the header of the main index.html file.

The <ccb-payment-widget> HTML tag is a non-standard element. You must tell the Angular app to use this element by defining a schema.

Add the CUSTOM_ELEMENTS_SCHEMA to the @NgModule decorator in the app.module.ts file.

If using standalone components, add the schema within the @Component decorator.

2. Usage

The Angular application is now aware of possible custom elements.

Add the custom <ccb-payment-widget> HTML tag in the app.component.html component template to enable the app to use these elements.

There are two ways to add the widget element to your template file:

Standard HTML Element

HTML Element with Self-closing Tags

The Angular application can now consume the widget but lacks the required configuration.

To initialize the widget, define the required parameters and their values in the app.component.ts file so they can be used in the app.component.html template.

Attributes

To provide these values to the widget, add the appropriate attributes to the widget tag in the app.component.html template.

ValidInvalid

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

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.

When the event is caught, the onGenerateTokenId method is called with data as input, and you can use the payment token.

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 Dark and Light 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.component.ts 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:

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.

1. Install Dependencies

The backend code uses the Axios dependency to make HTTP requests. Install it with:

NPM:

Yarn:

Begin by importing the axios library.

2. Define Endpoints

The endpoints section defines the API endpoints you will use throughout the process.

The example uses three endpoints to demonstrate the charge flow:

1. tokenEndpoint allows requesting the CCBill Auth (Bearer) token required for authentication in subsequent operations.

2. nonThreedsTransactionEndpoint allows performing a non-3DSecured charge transaction using the payment token.

3. threedsTransactionEndpoint allows performing a 3DSecured charge transaction using the payment token and previously obtained SCA parameters.

3. Provide Client Credentials

Set your Merchant Application ID as the value of clientId, and the Merchant Secret as the value of clientSecret.

The example code will set the accessToken value when the script executes.

4. Add Data

Provide the appropriate data for the request. To create a charge, the following parameters are obtained using the payment widget:

1. The paymentToken previously obtained using the widget.

Ensure the client's IP address is added as a payload ipAddress or header X-Origin-IP) parameter.

2. TransactionData, including the client account number, subaccount, the initial price, and period.

3. If using 3DS, provide the ThreedsParameters previously obtained using the payment widget.

5. Generate Token

Create a function to fetch the OAuth token (getOAuthToken). The function requires the client ID, client secret, and token endpoint to request the token.

The token helps authenticate the payment requests.

6. Charge Transaction and Handle Response

ThechargeTransactionfunction performs the charge based on the provided endpoint, data, payment token, and generated access token.

If calling the function throws no errors, the response is passed to the handleResponse function.

In this case, it only logs the response data. In a realistic scenario, it would allow you to continue processing the transaction and return the response to your client.

7. Test Transaction

The code fetches the OAuth token based on the previously provided data.

If the access token is generated successfully, the code performs a non-3DS transaction and then a 3DSecure transaction, using the previously obtained SCA and other transaction data.

1. Install Dependencies

Add the dependencies for building and importing the libraries. For example, if using Maven, you need a pom.xml file that lists all the dependencies with version numbers you want to use:

2. Define Endpoints

The endpoints section defines the API endpoints you will use throughout the process.

The example uses three endpoints to demonstrate the charge flow:

1. getAuthToken allows requesting the CCBill Auth (Bearer) token required for authentication in subsequent operations.

2. createTransactionallows performing a non-3DSecured charge transaction using the payment token.

3. createThreedsTransactionallows performing a 3DSecured charge transaction using the payment token and previously obtained SCA parameters.

3. Provide Client Credentials

Set your Merchant Application ID as the value of username, and the Merchant Secret as the value of password.

The example code will set theaccess_tokenvalue when the script executes.

4. Add Data

Provide the appropriate data for the request. To create a charge, the following parameters are obtained using the payment widget:

1. The paymentToken previously obtained using the payment widget. Ensure the client's IP address is added as a payload (ipAddress) or header (X-Origin-IP) parameter.

2. TransactionRequestParams, including the client account number, subaccount, the initial price, and period.

3. If using 3DS, provide the ThreedsTransactionRequestParams previously obtained using the payment widget.

5. Generate OAuth Token

Create a function to fetch the OAuth token (getAuthToken). The function requires the username, password, and token endpoint to request the token.

The token helps authenticate the payment requests.

6. Charge Transaction and Handle Response

ThecreateTransactionand createThreedsTransaction functions perform the charge based on the provided endpoint, data, payment token, and generated access token.

If calling the functions throws no errors, the response is passed to the TransactionResponse function.

In this case, it only logs the response data. In a realistic scenario, it would allow you to continue processing the transaction and return the response to your client.

7. Test Transaction

The code fetches the OAuth token based on the previously provided data.

If the access token is generated successfully, the code performs a non-3DS transaction and then a 3DSecure transaction using the previously obtained SCA and other transaction data.

1. Install Libraries

The Python backend uses the requests library to send API requests. Download the module using the PIP package manager:

Import the requests library and the requests.HTTPBasicAuth module.

2. Define Endpoints

The endpoints section defines the API endpoints you will use throughout the process. The example uses three endpoints to demonstrate the charge flow:

1. token_endpoint allows requesting the CCBill Auth (Bearer) token required for authentication in subsequent operations.

2. non_threeds_transaction_endpoint allows performing a non-3DSecured charge transaction using the payment token.

3. threeds_transaction_endpoint allows performing a 3DSecured charge transaction using the payment token and previously obtained SCA parameters.

3. Provide Client Credentials

Set your Merchant Application ID as the value of client_id and the Merchant Secret as the value of client_secret.

The example code will set the accessToken value when the script executes.

4. Add Data

Provide the appropriate data for the request. To create a charge, the following parameters are obtained using the payment widget:

1. The payment_token previously obtained using the payment widget.

Ensure the client's IP address is added as a payload (ipAddress) or header (X-Origin-IP) parameter.

2. transaction_data, including the client account number, subaccount, the initial price, and period.

3. If using 3DS, provide the threeds_parameters previously obtained using the payment widget.

5. Generate Token

Create a function to fetch the OAuth token (get_oauth_token). The function requires the client ID, client secret, and token endpoint to request the token.

The token helps authenticate the payment requests.

6. Charge Transaction and Handle Response

The charge_transaction function performs the charge based on the provided endpoint, data, payment token, and generated access token.

If calling the function throws no errors, the response is passed to the handle_response function.

In this case, it only logs the response data. In a realistic scenario, it would allow you to continue processing the transaction and return the response to your client.

7. Test Transaction

The code fetches the OAuth token based on the previously provided data.

If the access token is generated successfully, the code performs a non-3DS transaction and then a 3DSecure transaction using the previously obtained SCA and other transaction data.