API Reference - Online Checkout

This enables you to create a checkout invoice by providing the necessary details for your Customer to make payment.

Payment can be via mobile money, debit/credit card, GHQR, or Hubtel wallet. After making a payment, your website is notified through a redirect, and your online system is also notified by a web callback.

Request Parameters

Parameter	Type	Requirement	Description
totalAmount	Float	Mandatory	Specifies the total amount expected to be paid for the Items being purchased.
description	String	Mandatory	Describes to customers actions they can perform on the checkout page.
callbackUrl	String	Mandatory	The callback URL registered to receive the final notification on the status of the payment.
returnUrl	String	Mandatory	The merchant website URL where the customer should return after payment.
cancellationUrl	String	Mandatory	The merchant website URL where the customer should return after cancellation.
clientReference	String	Mandatory	A unique string identifying the request. Useful for reference purposes. It cannot be empty but must have a maximum of 32 characters.
PayeeName	String	Optional	This refers to the name of the Payee.
PayeeMobileNumber	String	Optional	This refers to the mobile number of the Payee.
PayeeEmail	String	Optional	This refers to the Email of the Payee.

Response Parameters

Parameter	Type	Description
checkoutUrl	String	A payee should be redirected to this link to make payment.
checkoutId	String	Unique Hubtel reference for transaction.
clientReference	String	This is a unique string identifying the request. Same as what was parsed in the request.
checkoutDirectUrl	String	A payee can make payment on the same page request was made from with this URL.

Sample Request

POST https://payproxyapi.hubtel.com/items/initiate
Host: test.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza24=
Cache-Control: no-cache

{  
  "totalAmount": 100,
  "description": "Book Shop Checkout",
  "callbackUrl": "https://webhook.site/8b4bbd0a-5f98-4b3d-abbe-b9b49767f7d5",
  "returnUrl": "http://hubtel.com/online",
  "merchantAccountNumber": "11684",
  "cancellationUrl": "http://hubtel.com/online",
  "clientReference": "inv0012"
}

Sample Response

{
    "responseCode": "0000",
    "status": "Success",
    "data": {
        "checkoutUrl": "https://pay.hubtel.com/7569a11e8b784f21baa9443b3fce31ed",
        "checkoutId": "7569a11e8b784f21baa9443b3fce31ed",
        "clientReference": "inv0012",
        "message": "",
        "checkoutDirectUrl": "https://pay.hubtel.com/7569a11e8b784f21baa9443b3fce31ed/direct"
    }
}