From 6a5d8c780b920fd99a04b1dd53f5cf293d65756c Mon Sep 17 00:00:00 2001 From: Isaac Afful Date: Wed, 14 Aug 2024 07:56:43 +0000 Subject: [PATCH] chore: Update package.json and CheckoutSdk.ts --- README.md | 269 +++++++++++++++++++++++++++++---------------- package.json | 9 +- src/CheckoutSdk.ts | 16 +-- 3 files changed, 185 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index 0247602..acff1b7 100644 --- a/README.md +++ b/README.md @@ -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 + ``` ## 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: @@ -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", @@ -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 + + + ... + + +
+ ... + + + +``` + +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 - }); -} -``` \ No newline at end of file + 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. | diff --git a/package.json b/package.json index 1d1a4ce..a657c17 100644 --- a/package.json +++ b/package.json @@ -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", @@ -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", @@ -22,5 +22,8 @@ "license": "MIT", "devDependencies": { "typescript": "^4.0.0" + }, + "dependencies": { + "user": "^0.0.0" } } diff --git a/src/CheckoutSdk.ts b/src/CheckoutSdk.ts index cca9e1c..c2e119a 100644 --- a/src/CheckoutSdk.ts +++ b/src/CheckoutSdk.ts @@ -73,7 +73,7 @@ interface Config { * @requires * The integration type. This can be either "Internal" or "External". */ - integrationType: "Internal" | "External"; + integrationType?: "Internal" | "External" | null; } @@ -236,9 +236,9 @@ class CheckoutSdk { const iframe = document.createElement("iframe"); iframe.src = this.createCheckoutUrl(purchaseInfo, config); iframe.style.display = "none"; - iframe.style.width = iframeStyle?.width || "100%"; - iframe.style.height = iframeStyle?.height || "100%"; - iframe.style.border = iframeStyle?.border || "none"; + iframe.style.width = iframeStyle?.width ?? "100%"; + iframe.style.height = iframeStyle?.height ?? "100%"; + iframe.style.border = iframeStyle?.border ?? "none"; iframe.onload = () => { iframeContainer.removeChild(loadingIcon); iframe.style.display = "block"; @@ -262,8 +262,7 @@ class CheckoutSdk { this.registerEvents(callBacks); this.renderWebpageInPopup( this.createCheckoutUrl(purchaseInfo, config), - // callBacks.onClose, - callBacks.onLoad, + callBacks.onClose, callBacks.onLoad ); } @@ -329,11 +328,8 @@ class CheckoutSdk { document.body.appendChild(modal); modal.style.opacity = "0"; iframe.addEventListener("load", () => { - if (onLoad) { - onLoad(); - } - modal.style.opacity = "1"; + onLoad?.(); }); }