Checkout API Reference

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 or Hubtel wallet. After making 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
amount	Double	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
reference	String	Mandatory	A unique string identifying the request. Useful for reference purposes. It cannot be empty but must have a maximum of 32 characters

Sample Request

POST https://domain.tapngogh.com HTTP/1.1
Host: https://api.pay.tapngogh.com
Accept: application/json
Content-Type: application/json
Authorization: <Authorization>


{  
  	"amount": 1,
	"reference": "test-reference",
	"description": "test-description",
	"callBackUrl": "https://webhook.site/8b4bbd0a-5f98-4b3d-abbe-b9b49767f7d5",
	
}

Request Example

Example

POST https://api.pay.tapngogh.com/payment/request-checkout

Headers

Name	Type	Description
Authorization*	String	Authorization for merchant

Request Body

Name	Type	Description
amount*	Double	Specifies the total amount expected to be paid for the Items being purchased.
reference*	String	A unique string identifying the request. Useful for reference purposes. It cannot be empty but must have a maximum of 32 characters
description*	String	describes to customers actions they can perform on the checkout page
callBackUrl	String	The callback URL registered to receive the final notification on the status of the payment.

200: OK

{
	"checkoutUrl": "https://pay.hubtel.com/9c262c34a52a4b399a1e9be076324142/direct",
	"responseCode": "0000",
	"status": "Success",
	"data": {
		"checkoutUrl": "https://pay.hubtel.com/9c262c34a52a4b399a1e9be076324142",
		"checkoutId": "9c262c34a52a4b399a1e9be076324142",
		"clientReference": "test-reference-4234345797347342",
		"message": "",
		"checkoutDirectUrl": "https://pay.hubtel.com/9c262c34a52a4b399a1e9be076324142/direct"
	}
}

400: Bad Request

Checkout Callback

You are required to implement a callback endpoint on your server to receive payment notification status on the payment or the order notification status.

We recommend using services like Webhook Tester, Request Catcher or ngrok to test your webhook callbacks. These services allow you to define temporary dummy endpoints which will show you the requests and all the data you are receiving from TapnGo.

Provide the dummy URL as the value for the PrimaryCallbackUrl or SecondaryCallbackUrl parameter.

Sample Web checkout Data

POST https://webhook.site/a8b36a02-5272-4a56-8e2b-15eab5e6bb71 HTTP/1.1
  Host: webhook.site
  Content-Type: application/json
  Cache-Control: no-cache
{
	"_id": "6378df8e7c21742154328cb6",
	"amount": 1,
	"fees": 0.01,
	"status": "success",
	"requestType": "direct",
	"merchant": "62c1ad1e5793ac631fc58ef3",
	"description": "test-description",
	"reference": "test-reference-4787823576",
	"callBackUrl": "[CallbackURL Here]",
	"customerEmail": "",
	"customerName": "",
	"customerPhone": "0548215801",
	"requestInfo": {
		"Message": "Transaction pending. Expect callback request for final state.",
		"ResponseCode": "0001",
		"Data": {
			"TransactionId": "8dcdfc7a64c040e4ad5be610323d3993",
			"Description": "test-description",
			"ClientReference": "test-reference-4787823576",
			"Amount": 1.01,
			"Charges": 0.02,
			"AmountAfterCharges": 0.99,
			"AmountCharged": 1.01,
			"DeliveryFee": 0
		}
	},
	"createdAt": "2022-11-19T13:52:14.883Z",
	"updatedAt": "2022-11-19T14:02:43.836Z",
	"__v": 0,
	"callBackInfo": {
		"ResponseCode": "0000",
		"Message": "success",
		"Data": {
			"Amount": 1.01,
			"Charges": 0.02,
			"AmountAfterCharges": 0.99,
			"Description": "The MTN Mobile Money payment has been approved and processed successfully.",
			"ClientReference": "test-reference-4787823576",
			"TransactionId": "8dcdfc7a64c040e4ad5be610323d3993",
			"ExternalTransactionId": "20424693259",
			"AmountCharged": 1.01,
			"OrderId": "8dcdfc7a64c040e4ad5be610323d3993"
		}
	},
	"callBackTime": "2022-11-19T14:02:43.836Z"
}