Table of Contents

1. Introduction
2. Set Up
3. Using The Widgets
4. For Development
5. Widget Properties
6. PayBox REST API

PayBox Widgets

This project contains the PayBox checkout and donation widgets. Support

Before using the widgets

1. Sign up on paybox.com.co
2. After verifying your account via email, head to your dashboard then click on 'API/Widget' on the sidebar
3. You should see your COLLECTION_KEY (Not to be mistaken with the 'transfer_key') in the 'Bearer Tokens' section. You will need these tokens when using the PayBox widgets and API.

Using The Widgets

The recommended way to use the widgets:

HTML script tag (recommended)

• Add the script tag to your HTML head like so <script type='module' src='https://unpkg.com/[email protected]/dist/checkout-widget/checkout-widget.esm.js'></script>. Replace x.x.x with the current package version found here.
• Then you can use the element anywhere in your template like in the examples below. The description of the widget properties can be found here

Donation Widget Example

<!-- Donation Widget Example -->
<paybox-donation-widget merchant_key="<merchant_collection_key>" payer_name="John Doe" payer_phone="+233xxxxxxxxx" email="[email protected]"></paybox-donation-widget>

Checkout Widget Example

<!-- Checkout Widget Example -->
<paybox-checkout-widget merchant_key="<merchant_collection_key>" payer_name="John Doe" payer_phone="+233xxxxxxxxx" email="[email protected]" amount="1" currency="GHS" reload></paybox-checkout-widget>

Node Modules

• Run npm install my-component --save
• Put a script tag similar to this <script type='module' src='https://unpkg.com/[email protected]/dist/checkout-widget/checkout-widget.esm.js'></script> in the head of your index.html
• Then you can use the element anywhere in your template, JSX, html etc

In a stencil-starter app

• Run npm install my-component --save
• Add an import to the npm packages import my-component;
• Then you can use the element anywhere in your template, JSX, html etc

For Development

To make changes to this project, clone this repo to a new directory:

git clone https://github.com/payboxglobal/checkout-widget.git checkout-widget
cd checkout-widget
git remote rm origin

and run:

npm install

You can then make code changes.

To start the project run:

npm start

To build the project for production, run:

npm run build

To run the unit tests for the components, run:

npm test

Widget Properties

Some of these properties are needed to initiate a payment on the widgets, others will be sent as additional data to the callback URL set on your PayBox dashboard.

| Property | Data type | Description | Included in payload | |-----------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------|---------------------| | merchant key | string | Your PayBox merchant collection key | No | | amount | number | Amount of money being with drawn | Yes | | phone_number (optional) | string | Phone number to send payment status to (Not payer Mobile Money number) | No | | payer_name (optional) | string | Name of the payer | No | | currency | string | The currency in which the payment is made (e.g., USD, EUR) | No | | payload (optional) | string | Additional data sent along with the payment request. | Yes | | reload (optional) | boolean | Indicates if the payment process should trigger a reload (false by default) | No | | redirect_url (optional) | string | URL to redirect to after the payment is completed | No | | order_id (optional) | string | Unique identifier for the order associated with the payment. | Yes | | customer_id (optional) | string | Unique identifier for the customer making the payment. | Yes | | email (optional) | string | Email of the payer | Yes | | payer_phone | string | The phone number from which Mobile Money payments will be initiated if the Mobile Money payment option is selected in the UI | Yes |

REST API

If you prefer to use the API's directly for collections and transfers, here is a link to the Postman collection.