Skip to main content

Widget Integration

Welcome to the integration guide for the CentsJS widget. In this section, you will find detailed information about the integration process, including how the flow works, how to import and use CentsJS, and how to send us a notification when an order is fulfilled.

Cause selection and order fulfillment - Sequence flow​

If you have a cart token, a unique identifier of the cart in the checkout page (or any analogous identifier to identify the order before it is placed), use this solution. Otherwise, choose the Without Cart Token tab.

  1. When the consumer user goes to the cart, the consumer user sees a Cents widget (via CentsJS). This widget loads charities and allows the user to select one of them.

    1. The consumer user selects a charity, and this info is tracked on Cents' server with additional context info (e.g., order amount), including the cart token passed as the reconciliation_id parameter. This reconciliation_id is necessary to reconcile this choice in the backend call to Cents' server when the order is fulfilled.

    2. After the consumer user has made a choice, a frontend callback is fired. If the donation is made by the user, the store has to add the donation item to the cart.

    3. When the order is fulfilled, the store should call a webhook/API to CentsJS, passing the order’s final data and reconciliation_id to reconcile this information with the previous ones. This ensures that the order is paid, so the donation can be considered complete. This must be done via the backend for security purposes.

Import​

To integrate the CentsJS widget, you need to implement the CentsJS frontend library, which loads the widget dynamically via the Cents API.

Import the following script to the page where you want to use Cents:

This JS script dynamically loads the CentsJS library in the background. It is possible to call library functions before the library is fully loaded as they are enqueued and executed as soon as the library is loaded.

<script>
    (function (c, e, n, t, s, d, o, a) {
        c[t] = c[t] || function () {
                (c[t].d = c[t].d || []).push({time: new Date().getTime(), event: arguments})
            }
        c[t]('init')
        o = e.getElementsByTagName(n)[0]
        a = e.createElement(n)
        a.async = true
        a.src =
            'https://api.centsdonations.com/v1/pub/'+s+'/'+d+'/lib/cents.js'
        o.parentNode.insertBefore(a, o)
    })(window, document, 'script', 'cents', 'company', 'COMPANY_ID_TO_BE_PROVIDED')
  </script>
  <div id="cents-div"></div>
info

Alternatively, the previous code can be automatically retrieved by calling (using OAuth2) https://api.centsdonations.com/v1/auth/company/lib/cents.html

note

The widget will be shown in the created div cents-div. The div could be placed in any part of the page.

Example - how to initialize the library​

Use the following JS code to initialize the library and manage the frontend callback.

Initialize​

cents('set_context_data', {amount: 5055, currency: 'EUR', userProvince: 'MI', userId: '155679729', pageType: 'product|cart', language: 'it', cartItems: [], userFullName: "usern full name", userEmail: "user email"}) //amount is indicated in the smallest currency unit, so 1000 is 10.00€ 
cents('show', document.querySelector('#cents-div'))
Additional data

The transaction data object can contain additional data that are not defined yet. For example, if you want to track additional info for the products to apply different logics, do not hesitate to contact us to understand the best format for you.

Product page banner

This widget allows consumer users to be informed about the donation process on every product page (using page_type = 'product') and enables them to choose a cause during the checkout/cart process (using page_type = 'cart').

note

In case of using cart token way pass here the reconciliation_id as reconciliationId parameter

Transaction complete callback​

cents('on_completed', ({transactionId, reconciliationId, donationAmount, donationPercentage, donationCause, donationCharity})=>{
  // Store reconciliationId to be sent with webhook when the order is fulfilled
})

CentsJS API​

To call every method of CentsJS simply call cents function, passing the API name as the first argument and the parameters as the second.

set_context_data(contextObject)​

This method should be called before show to set context data useful for AI logic.

parameters​

  • contextObject: ContextData → A dynamic object containing all relevant context data (e.g., user data, previous transactions, store info, page type, etc.).

types​

type ContextData = {
  pageType: 'product' | 'cart'
  amount?: number
  currency?: string
  userProvince?: string
  userId?: string
  language?: string
  userEmail?: string
  userFullName?: string
  reconciliationId?: string
  flow?: string
  additionalData?: any
  cartItems?: CartItem[]
}

type CartItem = {
  externalId: string
  quantity: number
  unitPrice: number
  discount: number
  totalPrice: number
}

show(element)​

This method should be called after set_context_data, to load the charities and display the HTML in the specified document element. It can be called multiple times in different HTML elements. If called again, the list of charities is refreshed, and so is the div content.

parameters​

  • element: Element → The document element where the Cents HTML should be displayed to show the charities.

on_completed(callback)​

his method sets the callback, which is fired when the CentsJS flow is completed (i.e., the user has chosen the cause). This callback should be used to store the reconciliation_id to be passed in the webhook/API when the order is fulfilled.

types​

type callbackData = {
  transactionId: string
  reconciliationId: string
  donationAmount: number //in the smallest currency unit, so 1000 is 10.00€
  donationPercentage?: number
  donationCharity: string
  donationCharityDisplayedName: string
  donationCause: string
  donationCauseName: string
  donationCauseDescription: string
  charityPaymentGatewayId?: string
  donationMadeBy: 'company' | 'consumer_user'
  autoChoice: boolean
  hmac: string
}

parameters​

  • callback: (data: callbackData) => void → This is the callback called when the flow is completed. It has one argument, which is the callbackData object containing all needed data.

Webhook/API​

To track the transaction when the order is fulfilled and reconcile this information with the previous data selected by the consumer user using CentsJS, you have to pass the reconciliation_id. Track a Transaction API Endpoint

Only donation_amount, donation_currency, and reconciliation_id are mandatory since the charity is already passed by CentsJS.

tip

All APIs related to companies are described here.

To use these APIs, a specific user will be provided to you, and you must use the OAuth2 flow to authenticate APIs.

Alternative Solutions

For this step, alternative solutions such as CSV batch can be evaluated.

Authentication​

Resource

See resource: OAuth2 Authentication.

System Integration Testing Environment (SIT)​

In the test environment (SIT), the URLs are different from those in the production environment:

Url inside CentsJS library:​

https://api.centsdonations.com/v1/pub/'+s+'/'+d+'/lib/cents.js

Url to get CentsJS library (as HTML):​

https://api.centsdonations.com/v1/auth/company/lib/cents.html

Sign-in url:​

https://cents-api.auth.eu-west-1.amazoncognito.com/oauth2/authorize?client_id=51jaa1t8nvjsckbqns00p53ii1&response_type=code&scope=openid&redirect_uri=https%3A%2F%2Fapi.centsdonations.com%2Fv1%2Fpub%2Fcompany%2Fstart

Refresh token call:​

curl -X POST \
  https://cents-api.auth.eu-west-1.amazoncognito.com/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id=51jaa1t8nvjsckbqns00p53ii1&refresh_token=REFRESH_TOKEN&redirect_uri=https%3A%2F%2Fapi.centsdonations.com%2Fv1%2Fpub%2Fcompany%2Fstart'

Contacts​

For further assistance, please contact us at: tech@centsdonations.com