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.

Import​

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

<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', 'payment-gateway', 'PAYMENT_GATEWAY_ID_TO_BE_PROVIDED')
  </script>
  <div id="cents-div"></div>

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

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

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​

Call the following JS to initialize the library and manage the frontend callback

Initialize​

cents('set_context_data', {amount: 5055, currency: 'EUR', userProvince: 'MI', userId: '155679729', language: 'it', cartItems: []}) //amount is indicated in the smallest currency unit, so 1000 is 10.00€
cents('show', document.querySelector('#cents-div'))
note

The transaction data object may include extra data that has not been defined yet. For instance, if you need to monitor additional information for the products to implement different strategies, feel free to reach out to us for guidance on the most suitable format for your needs.

Transaction complete callback​

cents('on_completed', ({transactionId, reconciliationId, donationAmount, donationPercentage, donationCause, donationCharity})=>{
  //TODO perform transaction using donationAmount as import of the donation
  //TODO Store reconciliationId (donation transaction id) to be sent with webhook when the order is fulfilled (only in the 'donation as single transaction' scenario)
})

CentsJS API​

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

set_context_data(contextObject)​

To be called before the show, it’s used to set context data useful for AI logic.

parameters​

  • contextObject: ContextData → dynamic object which contains all relevant data of the context (data of the user, the previous transaction, the store, and so on).

types​

type ContextData = {
  pageType: 'product' | 'cart'
  amount?: number
  currency?: string
  userProvince?: string
  userId?: string
  language?: string
  userEmail?: string
  userFullName?: string
  reconciliationId?: string //it's the donation transaction id
  flow?: string
  additionalData?: any
  cartItems?: CartItem[]
  paymentGatewayData?: {
    companySector?: string
    companyId?: string
    paymentGatewayCompanyId?: string
    paymentGatewayOrderTransactionId?: string
  }
}

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

show(element)​

To be called after set_context_data, it is used to load the charities and to load the HTML to show them into the specified document element. It could be loaded multiple times in different HTML elements. If it is called again, the list of charities is refreshed and so is the div content.

parameters​

  • element: Element → the document element where to load the Cents HTML to show the charities.

on_completed(callback)​

To be called to set the callback, which is fired when the CentsJS flow is completed i.e. the user has chosen the cause.

types​

type callbackData = {
  transactionId: string
  reconciliationId: string //it's the donation transaction id
  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 only one argument, which is the callbackData object containing all needed data

Webhook/API​

To track the transaction when the order is fulfilled. To reconcile this information with the previous data selected by the consumer user using CentsJS you have to pass the transactionId as reconciliationId 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 payment gateway are described here

To use these API a specific user will be provided to you, and you have to use 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/payment-gateway/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%2Fpayment-gateway%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%2Fpayment-gateway%2Fstart'

Contacts​

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