CCBill API Payment Widget integration guide

React

Complete the following steps to integrate the Payment Widget into your React application.

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

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

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

RequiredOptional
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
ValidInvalid

If all the passed parameters are correct, the following screen appears:

A successfully configured CCBill API Payment Widget.

In case of a misconfiguration or if one of the values passed in is not valid, the following screen is displayed:

CCBill Widget misconfiguration message.

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.

CCBill Widget successfully configured.

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:

Base Template ColorElement Template ColorsValidation Input Fields
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 --ccb-validation-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.

index.html App.tsx styles.css 

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" /><link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
<base href="/" />

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>

<link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
<link rel="manifest" href="%PUBLIC_URL%/manifest.json" />

<link rel="stylesheet" href="styles.css"/>

<title>DemoReactMerchant</title>

<script src="https://js.ccbill.com/payment-widget/v1/index.js"></script>
</head>
	<body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
<div id="root"></div>
  </body>
</html>






import React, { useState } from 'react';
import './App.css';

declare global {
  namespace JSX {
    interface IntrinsicElements {
      "ccb-payment-widget": MyElementAttributes;
    }

    interface MyElementAttributes {
      apiKey: string;
      clientAccount: string;
      subAccount: string;
      currency: string;
      initialPrice: string;
      initialPeriod: string;
      language?: string;
      description?: string;
      recurringPrice?: string;
      recurringPeriod?: string;
      rebills?: string;
      lifeTimeSubscription?: string;
      theme?: string;
    }
  }
}

interface PaymentToken {
  paymentTokenId: string;
  programParticipationId: string;
  originalPaymentTokenId: string;
  clientAccnum: number;
  clientSubacc: number;
  createdDatetime: Date;
  timeToLive: number;
  validNumberOfUse: number;
  subscriptionId: string;
  paymentInfoId: string;
  errors: {};
}

function App() {
  const [paymentToken, setPaymentToken] = useState(null);

  // Required parameters
  const apiKey =
    "YOUR-API-KEY";
  const initialPrice = "0.00";
  const initialPeriod = "0";
  const currency = "USD";
  const clientAccount = "900000";
  const subAccount = "0";
// Set theme value here
  const theme = "ccb-light";


// Register event listener for token generation
  React.useEffect(() => {
    window.addEventListener("tokenCreated", _onGenerateTokenId);

    return () => {
      window.removeEventListener("tokenCreated", _onGenerateTokenId);
    };
  }, []);


// Handle behaviour on tokenCreated event
  function _onGenerateTokenId(event: Event) {
    const receivedPaymentToken = (event as CustomEvent).detail
      .paymentToken as PaymentToken;

    setPaymentToken(receivedPaymentToken);
  }

    return (
    <div>
      {paymentToken ? (
        <div>
          <h2>Payment Token Generated</h2>
          <pre>{JSON.stringify(paymentToken, null, 2)}</pre>
        </div>
      ) : (
        <p>No payment token available yet.</p>
      )}

      <ccb-payment-widget
          apiKey={apiKey}
          currency={currency}
          initialPrice={initialPrice}
          initialPeriod={initialPeriod}
          clientAccount={clientAccount}
          subAccount={subAccount}
 theme={theme}
          />          
     </div>
  );
}

export default App;

			html {
			  /* Custom - Background */
			  --ccb-background: #280F50;

			  /* Custom - Header - Ribbon */
			  --ccb-ribbon-background: #62389E;
			  --ccb-header-language-dropdown-text: #ffffff;
			  --ccb-header-language-dropdown-icon: #ffffff;
			  --ccb-header-language-background: #62389E;

			  /* Add more customizations here */
			}