Skip to content

Latest commit

 

History

History
263 lines (197 loc) · 10.1 KB

README.md

File metadata and controls

263 lines (197 loc) · 10.1 KB
Raw

Hubtel Web Merchant Checkout SDK

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 CDN link in your HTML file:

NPM

npm i @hubteljs/checkout

CDN

<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.

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

Pre Checkout

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:

{
  "amount": "1",
  "phoneNumber": "0200000000"
}

Sample Pre-checkout Response:

{
  "message": "success",
  "code": "200",
  "data": {
    "description": "Payment of GHS 50.00 for (18013782) (MR SOMUAH STA ADANE-233557913587) ",
    "clientReference": "f03dbdcf8d4040dd88d0a82794b0229f",
    "amount": 1.0,
    "customerMobileNumber": "233557913587",
    "callbackUrl": "https://instantservicesproxy.hubtel.com/v2.1/checkout/callback"
  }
}

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

// 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 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 = () => {
  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),
    },
  });
};

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

// 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.

Example Usage

In your HTML file, add a div element with the id hubtel-checkout-iframe where you want the checkout to be rendered.

 
 <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.

// 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",
};

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.

Contribution

We welcome contributions from the developer community to improve the Hubtel Checkout SDK. To contribute:

  1. Fork the Repository: Start by forking the Hubtel Checkout SDK repository on GitHub.

  2. Create a Feature Branch: Create a new branch for your feature or bugfix.

  3. Implement Your Changes: Make your code changes or improvements.

  4. Write Tests: Write tests for your code changes or improvements.

  5. Submit a Pull Request: Push your changes to your forked repository and submit a pull request for review.