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 made via Mobile Money, Bank Card, G-Money, Zeepay, GHQR, BankPay 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	A brief description about the item to be purchased.
callbackUrl	String	Mandatory	The callback URL expected to receive the final status of the payment.
returnUrl	String	Mandatory	The merchant website URL where the customer should be redirected to after payment.
cancellationUrl	String	Mandatory	The merchant website URL where the customer should be redirected to 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	A unique Hubtel reference for the 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: payproxyapi.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"
    }
}