Skip to content

Commit

Permalink
Merge pull request #2 from hubtel/dev
Browse files Browse the repository at this point in the history 
chore: Update package.json and documentation
  • Loading branch information
@affulisaac
affulisaac authored Aug 14, 2024
2 parents b454abb + 6a5d8c7 commit 5113f0d
Show file tree
Hide file tree
Showing 3 changed files with 185 additions and 109 deletions.
269 changes: 173 additions & 96 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,38 @@

# External Unified Checkout SDK Integration Documentation

## Overview
The Checkout SDK provide seamless way for businesses to accept payment from their customers. The SDK offers three primary methods of integration: Redirect, Iframe, and Modal. This provides flexibility for developers to choose the integration method that best suits their needs.

The Checkout SDK provide seamless way for businesses to accept payment from their customers. The SDK offers three primary methods of integration: Redirect, Iframe, and Modal. This provides flexibility for developers to choose the integration method that best suits their needs.

## Installation

To use the Hubtel Checkout SDK to collect payment, install the NPM Package or include the the CDN link in your HTML file:
To use the Hubtel Checkout SDK to collect payment, install the NPM Package or include the CDN link in your HTML file:

`NPM`

```bash
npm install hubtel-checkout
npm i @hubteljs/checkout
```

`CDN`

```html
<script src="https://unified-pay.hubtel.com/js/v1/checkout.js"></script>
```

## Methods of Integration

The Hubtel Checkout SDK supports three primary methods of integration:

**1. Modal Integration:** This method opens the checkout page in a modal popup

**2. Redirect Integration:** This method opens the checkout page in a new tab or window.
**2. Redirect Integration:** This method opens the checkout page in a new tab or window.

**3. Iframe Integration:** This method embeds the checkout page within an iframe on your webpage.

## Pre Checkout



**Note**: Before calling the Checkout SDK, most internal apps would call a Pre-Checkout API provided by their backend team. The implementation might differ.
**Note**: Before calling the Checkout SDK, most apps would call a Pre-Checkout API provided by their backend team to create the order for the client app to handle the payment. The implementation might differ.

Sample Pre-checkout Request:

Expand All @@ -44,7 +50,7 @@ Sample Pre-checkout Response:
"message": "success",
"code": "200",
"data": {
"description": "Payment of GHS 1.00 for (18013782) (MR SOMUAH STA ADANE-233557913587) ",
"description": "Payment of GHS 50.00 for (18013782) (MR SOMUAH STA ADANE-233557913587) ",
"clientReference": "f03dbdcf8d4040dd88d0a82794b0229f",
"amount": 1.0,
"customerMobileNumber": "233557913587",
Expand All @@ -53,122 +59,193 @@ Sample Pre-checkout Response:
}
```

The response from the Pre-Checkout API usually contains all information needed for a successful checkout. Once retrieved the data is then passed onto the Hubtel Checkout SDK to begin the checkout.

**Note**: The above approach may not be applicable in your case.
The response from the Pre-Checkout API usually contains all information needed for a successful checkout. Once retrieved the data is then passed onto the Hubtel Checkout SDK to begin the checkout.


## Modal Integration

The modal integration method opens the checkout page in a modal popup. This is done by calling the `openModal` method of the Checkout SDK instance and passing the purchase information, configuration options and callBacks for event handling as parameters.


#### Example Usage

```javascript

// Import the Checkout SDK
import CheckoutSdk from "hubtel-checkout";
// Import the Checkout SDK if you are using the npm package
import CheckoutSdk from "@hubteljs/checkout";

// Initialize the Checkout SDK
const checkout = new CheckoutSdk();

// Call the initPay function to open the modal
// Purchase information
const purchaseInfo = {
amount: 50,
purchaseDescription:
"Payment of GHS 5.00 for (18013782) (MR SOMUAH STA ADANE-233557913587)",
customerPhoneNumber: "233557913587",
clientReference: "unique-client-reference-12345",
};

// Configuration options
const config = {
branding: "enabled",
callbackUrl: "https://yourcallbackurl.com",
merchantAccount: 11334,
basicAuth: "your-basic-auth-here",
};

// A function to open the payment modal
const initPay = () => {
const purchaseInfo = {
amount: 50,
purchaseDescription: 'Payment of GHS 1.00 for (18013782) (MR SOMUAH STA ADANE-233557913587)',
customerPhoneNumber: "233557913587",
clientReference: "unique-client-reference-12345",
};

const config = {
branding: "enabled",
callbackUrl: "https://yourcallbackurl.com",
merchantAccount: 11334,
basicAuth: "your-basic-auth-here",
};

checkout.openModal({
purchaseInfo,
config,
callBacks: {
onInit: () => console.log("Iframe initialized: "),
onPaymentSuccess: (data) => {console.log("Payment succeeded: ", data)
// You can close the popup here
checkout.closePopUp();
},
onPaymentFailure: (data) => console.log("Payment failed: ", data),
onLoad: () => console.log("Checkout has been loaded: "),
onFeesChanged: (fees) => console.log("Payment channel has changed: ", fees),
onResize: (size) => console.log("Iframe has been resized: ", size?.height),
onClose: (size) => console.log("The modal has closed ", size?.height),
checkout.openModal({
purchaseInfo,
config,
callBacks: {
onInit: () => console.log("Iframe initialized: "),
onPaymentSuccess: (data) => {
console.log("Payment succeeded: ", data);
// You can close the popup here
checkout.closePopUp();
},
});
}
onPaymentFailure: (data) => console.log("Payment failed: ", data),
onLoad: () => console.log("Checkout has been loaded: "),
onFeesChanged: (fees) =>
console.log("Payment channel has changed: ", fees),
onResize: (size) =>
console.log("Iframe has been resized: ", size?.height),
onClose: (size) => console.log("The modal has closed ", size?.height),
},
});
};
```
#### Parameters
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------- |
| **purchaseInfo** | Object | Contains details about the purchase. |
| `amount` | number | The purchase amount. |
| `purchaseDescription` | string | A brief description of the purchase. |
| `customerPhoneNumber` | string | The customer’s phone number. |
| `clientReference` | string | A unique reference for the purchase. |
| **config** | Object | Contains configuration options. |
| `branding` | string | Set to "enabled" to show the business name and logo or "disabled" to hide them. |
| `callbackUrl` | string | The URL to which the SDK will send the response. |
| `merchantAccount` | number | The merchant account ID. |
| `basicAuth` | string | Basic auth credentials. |
| `integrationType` | string | Specifies the integration type. Default is "External" which is the type used for external integration. |
| **callacks** | Object | Callback functions for various events. |
| `onInit` | function | Called when the iframe is initialized. |
| `onPaymentSuccess` | function | Called when the payment is successful. |
| `onPaymentFailure` | function | Called when the payment fails. |
| `onLoad` | function | Called when the iframe is loaded. |
| `onFeesChanged` | function | Called when the fees change. |
| `onClose` | function | Called when the the modal is closed. |
## Redirect Integration
# Redirect Integration
The redirect method opens the checkout page in a new tab or window. This is done by calling the `redirect` method of the Checkout SDK instance and passing the purchase information and configuration options as parameters.
#### Example Usage
```javascript

// Import the Checkout SDK
import CheckoutSdk from "hubtel-checkout";
// Import the Checkout SDK if you are using the npm package
import CheckoutSdk from "@hubteljs/checkout";

// Initialize the Checkout SDK
const checkout = new CheckoutSdk();

//Purchase information
const purchaseInfo = {
amount: 50,
purchaseDescription:
"Payment of GHS 50.00 for (18013782) (MR SOMUAH STA ADANE-233557913587)",
customerPhoneNumber: "233557913587",
clientReference: "unique-client-reference-12345",
};

// Configuration options
const config = {
branding: "enabled",
callbackUrl: "https://yourcallbackurl.com",
merchantAccount: 11334,
basicAuth: "your-basic-auth-here",
};

// A function to redirect to the payment page
const redirect = () => {
checkout.redirect({
purchaseInfo,
config,
});
};
```
# Iframe Integration
The iframe integration method embeds the checkout page within an iframe on your webpage. This method is suitable for developers who want to keep their users on the same page while making a payment.
const redirect = () =>{
#### Example Usage
In your HTML file, add a div element with the id `hubtel-checkout-iframe` where you want the checkout to be rendered.
```html

<body>
...
<!-- Add this element to where you want the checkout to be rendered. By default the checkout will use the available height and width of it's container -->
<div id="hubtel-checkout-iframe"></div>
...
</body>
```
In your JavaScript file, call the `initIframe` method of the Checkout SDK instance and pass the purchase information, configuration options, iframe style and callBacks for event handling as parameters.
```javascript
// Import the Checkout SDK if you are using the npm package
import CheckoutSdk from "@hubteljs/checkout";
// Initialize the Checkout SDK
const checkout = new CheckoutSdk();
//Purchase information
const purchaseInfo = {
amount: 50,
purchaseDescription: 'Payment of GHS 1.00 for (18013782) (MR SOMUAH STA ADANE-233557913587)',
customerPhoneNumber: "233557913587",
clientReference: "unique-client-reference-12345",
};

const config = {
branding: "enabled",
callbackUrl: "https://yourcallbackurl.com",
merchantAccount: 11334,
basicAuth: "your-basic-auth-here",
};

checkout.redirect({
purchaseInfo,
config
});
}
```
amount: 50,
purchaseDescription:
"Payment of GHS 50.00 for (18013782) (MR SOMUAH STA ADANE-233557913587)",
customerPhoneNumber: "233557913587",
clientReference: "unique-client-reference-12345",
};
// Configuration options
const config = {
branding: "enabled",
callbackUrl: "https://yourcallbackurl.com",
merchantAccount: 11334,
basicAuth: "your-basic-auth-here",
};
const iframeStyle = {
width: '100%',
height: '100%',
border: 'none',
};
// A function to render the iframe on the page where the div with id 'hubtel-checkout-iframe' is located
const openIframe = () => {
checkout.initIframe({ purchaseInfo, config, iframeStyle, callBacks: {
onInit: () => console.log('Checkout initialize Initialized'),
onPaymentSuccess: (data) => console.log('Payment Success', data),
onPaymentFailure: (data) => console.log('Payment Failure', data),
onLoad: () => console.log('Iframe Loaded'),
onFeesChanged: (fees) => console.log('Fees Changed', fees),
onResize: (size) => console.log('Iframe Resized', size?.height),
}})
};
```
#### Parameters
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| **purchaseInfo** | Object | Contains details about the purchase. |
| `amount` | number | The purchase amount. |
| `purchaseDescription` | string | A brief description of the purchase. |
| `customerPhoneNumber` | string | The customer’s phone number. |
| `clientReference` | string | A unique reference for the purchase. |
| **config** | Object | Contains configuration options. |
| `branding` | string | Set to "enabled" to show the business name and logo or "disabled" to hide them. |
| `callbackUrl` | string | The URL to which the SDK will send the response. |
| `merchantAccount` | number | The merchant account ID. |
| `basicAuth` | string | Basic auth credentials. |
| `integrationType` | string | Specifies the integration type. Default is "External" which is the type used for external integration. |
| **callacks** | Object | Callback functions for various events. |
| `onInit` | function | Called when the checkout is initialized. |
| `onPaymentSuccess` | function | Called when the payment is successful. |
| `onPaymentFailure` | function | Called when the payment fails. |
| `onLoad` | function | Called when the iframe or modal is loaded. |
| `onFeesChanged` | function | Called when the the user select a different payment channel |
| `onClose` | function | Called when the the modal is closed. |
| `onResize` | function | Called when the iframe have been resized closed. |
9 changes: 6 additions & 3 deletions package.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "hubtel-checkout",
"version": "1.0.6",
"name": "@hubteljs/checkout",
"version": "1.0.7",
"description": "A JavaScript SDK for handling checkout processes.",
"main": "dist/CheckoutSdk.js",
"types": "dist/CheckoutSdk.d.ts",
Expand All @@ -10,7 +10,7 @@
},
"repository": {
"type": "git",
"url": "https://github.com/isaac_afful/hubtel-checkout"
"url": "https://github.com/hubtel/hubtel-web-merchant-checkout-sdk.git"
},
"keywords": [
"checkout",
Expand All @@ -22,5 +22,8 @@
"license": "MIT",
"devDependencies": {
"typescript": "^4.0.0"
},
"dependencies": {
"user": "^0.0.0"
}
}
Loading

0 comments on commit 5113f0d

Please sign in to comment.