carbon-zero-widget

Introduction
- Properties or Attributes
- Events
Vue Integrations
React Integrations
Angular Integrations
Vanilla Javascript Integration

Introduction

CarbonZero is a web component that connect the carbon payment api to your web app to allow your customers make payment with Carbon with the buy now pay later option.

This component is built as an HTML5 web component integrable with any frontend framework or frontend technology of your choice that uses HTML as it's building block.

The package is built to be install as a cdn through the unpkg into your project html page. The how to use for some popular framework is as described below. The underlying principle of using this package is similar from one framework to another.

NOTE: All amount or prices is expected in kobo for Nigeria users.

Properties or Attributes

The following are the properties or attributes to be provided when using the component.

Prop	Type	Required	Descriptions
total-price	Number	true	This is the gross price of the products/services customer wants to purchase. This includes the total cost price of the goods and all other charges (e.g shipping) made on the products or services being charged for.
purchase-items	Array	true	This is the array of items the customer purchased.
purchase-ref-id	String	true	This is the unique character created for the purchase refrence identification
merchant-id	String	true	The merchant id provided for you during registration
api-key	String	true	The API key provided for you during registration
country	String	false	The country where your aplication will be used. Default to Nigeria

## Events

Event	Descriptions
close-carbon-zero	This is the function called when the close icon is clicked

Vue Integrations

To import CarbonZero in a Vue app, add the code below to the head of the index.html

<!-- index.html -->
...
<script src="https://unpkg.com/carbon-zero-widget"></script>
...

Vue 3

<!-- your_component.vue -->
...
<template>
  ...
  <carbon-zero
    v-if="showZero"
    merchant-id=".......34c-50609dd17560"
    api-key="test_41344ef1-f4e1-43ed-b...."
    country="ng"
    total-price="2000000"
    class="carbon-zero"
    purchase-ref-id="rtghbvcghj76"
    purchase-items='[{"itemName": "iPhone 13", "itemQuantity": 1, "itemPrice": 2000000}'
    @closeCarbonZero="() => (showZero = false)"
  ></carbon-zero>
  <button @click="handleShowZero">Pay with Carbon Zero</button>
  ...
</template>
<!-- With setup -->
<script setup>
const showZero = ref(false)
const handleShowZero = () => (showZero.value = true)
</script>
...

Vue 2

<!-- your_component.vue -->
...
<template>
  ...
  <button class="btn btn-light" @click="checkout">Checkout</button>
  <carbon-zero
    v-if="showZero"
    merchant-id=".......34c-50609dd17560"
    api-key="test_41344ef1-f4e1-43ed-bc68...."
    country="ng"
    total-price="2000000"
    class="carbon-zero"
    purchase-ref-id="rtghbvcghj76"
    purchase-items='[{"itemName": "iPhone 13", "itemQuantity": 1, "itemPrice": 2000000'
    @closeCarbonZero="() => (showZero = false)"
  ></carbon-zero>
  ...
</template>
<script>
export default {
  data() {
    return {
      showZero: false
    }
  },
  methods: {
    checkout() {
      this.showZero = true
    }
  }
}
</script>
...

Setup for different build tools

When using CarbonZero with Vue, you have to specify it in you config.

Vue CLI

For Vue cli, add the following setting to your Vue config

// vue.config.js
module.exports = {
  // ...
  chainWebpack: (config) => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap((options) => ({
        ...options,
        compilerOptions: {
          // treat any tag that starts with ion- as custom elements
          isCustomElement: (tag) => tag.startsWith('carbon-')
        }
      }))
  }
}

Vite

For Vite, add the following setting to your Vite config

// vite.config.js
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // treat all tags with a dash as custom elements
          isCustomElement: (tag) => tag.includes('carbon-')
        }
      }
    })
  ]
}

React Integrations

When using CarbonZero in a react app, install the package to your app index page with

<!-- index.html -->
...
<script src="https://unpkg.com/carbon-zero-widget"></script>
...

Then create a wrapper component that can be used anywhere

// Carbon Zero Wrapper page

import React, { useState, useEffect } from 'react'

function CarbonZeroWrapper({ totalPrice, purchaseRefId, purchasedItems }) {
  const [showZero, setShowZero] = useState(false)

  const openZero = () => {
    setShowZero(true)
  }
  const closeZero = () => {
    return setShowZero(false)
  }
  useEffect(() => {
    if (showZero) {
      const zero = document.querySelector('.carbon-zero')
      zero.addEventListener('close-carbon-zero', () => {
        closeZero()
      })
    }
  }, [showZero])
  return (
    <div className="wrrapper">
      {showZero && (
        <carbon-zero
          class="carbon-zero"
          merchant-id={process.env.REACT_APP_CARBON_ZERO_MERCHANT_ID}
          api-key={process.env.REACT_APP_CARBON_ZERO_API_KEY}
          country="NG"
          total-price={totalPrice}
          purchase-ref-id={purchaseRefId}
          purchase-items={purchasedItems}
        ></carbon-zero>
      )}
      <button onClick={openZero}>Pay With Carbon Zero</button>
    </div>
  )
}

export default CarbonZeroWrapper

Angular Integrations

To integrate CarbonZero with an Angular app,

→ import CUSTOM_ELEMENTS_SCHEMA from @angular/core and declare it as shown below

@NgModule({
  ...
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})

→ Add <script src="https://unpkg.com/carbon-zero-widget"></script> to index.html header. and

→ Use CarbonZero widget anywhere in your app. An example is as shown below.

// checkout.component.html

<div role="checkout">
  <carbon-zero
    *ngIf="showZeroApp"
    class="carbon-zero"
    merchant-id="TWkCim"
    api-key="test_pk_uUgoo6VxPOKeNi3aMo6plr6Xgx8AO5"
    country="NG"
    total-price="2000000"
    purchase-ref-id="hfkwtgs"
    purchase-items='[{"itemName": "iPhone 13", "itemQuantity": 1, "itemPrice": 2000000}]'
    (onclosecarbonzero)="closeZero()"
  ></carbon-zero>
  <button (click)="openZero()">Pay with Carbon Zero</button>
</div>

// checkout.component.ts

import { Component } from '@angular/core'

@Component({
  selector: 'app-checkout',
  templateUrl: './checkout.component.html',
  styleUrls: ['./checkout.component.css']
})
export class AppComponent {
  showZeroApp = false
  openZero() {
    this.showZeroApp = true
  }
  closeZero() {
    this.showZeroApp = false
  }
}

Vanilla Javascript Integration

To import CarbonZero in a Vanilla Javascript application, add the code below to the head of the checkout.html

<!-- checkout.html -->
...
<head>
  <meta charset="UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Document</title>
  <link rel="stylesheet" href="./checkout.css" />
  <script type="module" src="https://unpkg.com/carbon-zero-widget"></script>
</head>
...

Then create a div component that can be used within the body tag of your HTML file

// Carbon Zero Wrapper section

<body>
  <div id="main">
    <button id="payment-button">Pay with Carbon Zero</button>
    <carbon-zero
      api-key="...goo6VxPOKeNi3aMo6plr6Xgx8AO5"
      merchant-id="TWkCim"
      total-price=""
      class="remove-zero"
      purchase-ref-id=""
      country="ng"
      purchase-items=""
    ></carbon-zero>
  </div>

  <script src="./checkout.js"></script>
</body>

On the Javascript file, set the values of the custom element attributes and the function to trigger the payment button

const itemsPurchased = JSON.stringify([{ itemName: 'iPhone 13', itemQuantity: 1, itemPrice: 20000 }])
const refId = 'purchaseRefId' + Math.floor(Math.random() * 2000)
const totalPrice = '200000'

// Setting dymanic values to Carbon Zero Props

const carbonZero = document.querySelector('carbon-zero')
carbonZero.setAttribute('purchase-items', itemsPurchased)
carbonZero.setAttribute('purchase-ref-id', refId)
carbonZero.setAttribute('total-price', totalPrice)

// Add an Event listener to the payment button

const paymentButton = document.getElementById('payment-button')
paymentButton.addEventListener('click', function () {
  carbonZero.classList.add('show-zero')
  carbonZero.classList.remove('remove-zero')
})

On the CSS file, add the code below

.show-zero {
  display: block;
}

.remove-zero {
  display: none;
}