carbon-zero-widget v1.1.1

TABLE OF CONTENTS

• Introduction
  • Properties or Attributes
  • Events
• Vue Integrations
  • Vue 3
  • Vue 2
  • Setup for different build tools
  • Vue CLI
  • Vite
• 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.

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;
}