Hubtel

Recurring Payments API Documentation

1
API Change Log
Changes between document issues are cumulative. The latest document issue contains all the changes made
in earlier issues.
v1.0 (2019-10-31)
This issue is the first official release
v1.1 (2019-12-12)
This issue contains a cancel invoice API endpoint.
v1.2 (2020-02-12)
This issue includes changes to the callback structure and additional payment channels.

2
Contents
API Change Log ....................................................................................................................................... 2

1.0 Overview ..................................................................................................................................... 4

2.0 Getting Started ........................................................................................................................... 4

2.1 Authentication ....................................................................................................................... 4

3.0 Understand the Service Flow ..................................................................................................... 5

4.0 API Reference ............................................................................................................................. 7

4.1 Create Invoice API .................................................................................................................. 7

4.2 Verify Invoice API ................................................................................................................. 11

4.3 Callback ................................................................................................................................. 12

4.4 Cancel Invoice API ................................................................................................................. 15

5.0 API Response Codes ................................................................................................................. 16

Contact Us .......................................................................................................................17

3
1.0 Overview

The Hubtel Recurring Payments API allows you to setup and receive recurring payments from
your customers for services provided using mobile money and card options.

With a single integration, you can easily and securely accept recurring mobile money
payments on your application. All you need to do is to simply provide the customer debit
details and Hubtel will handle the scheduling and the various debits.

The following provides an overview of the REST API endpoints for interacting
programmatically with the Hubtel Recurring P API within your application.

2.0 Getting Started

First you need to create a Hubtel Account to be able to use the Recurring Payments API.
If you already have a Hubtel account, then skip to step 2.

Step 1: Create a Hubtel Account

Step 2: Have the Account Verified and approved.

2.1 Authentication
You need to authenticate every API request you make to the Recurring Payments API
using Basic Auth. Authenticate by encoding your username and password to Base64 HTTP
Basic Authorization. Use your API ID as your username and API KEY as your password.

Login to your Hubtel account using https://app-site.hubtel.com/settings/integrations to

generate your API ID and API KEY.

A Base64 encoding of your API keys should have your Authorization header appear like this:
Basic a2hlcW2sb3U6bWdhtHd9YW8=.

You will also have to share your public IP address for whitelisting. Only requests from this IP
will be accepted. Send this via email to [email protected].

4
3.0 Understand the Service Flow
The Hubtel Recurring Payments service includes two main API endpoints which are used
together to setup a recurring payment invoice. They are

 Create Invoice Endpoint: This allows you to create a recurring payment invoice on a
customer wallet. The invoice will stay in a temporary state until the verification is
done. This step initiates the invoice creation process.
 Verify Invoice Endpoint: This allows you to verify the invoice with the customer
involvement through an OTP code. This completes the invoice creation process.

The entire process is asynchronous. The figure below shows the process of creating and
verifying a Recurring Payment Invoice using these two endpoints:

Hubtel Recurring Mobile Money

Customer Your App
Payments API Provider

InvoiceCreation Request
1

InvoiceCreation Response
2

OTP Code Sent to Customer

3
Customer provides your App with
OTP Code
4
VerifyInvoice Request
5

VerifyInvoice Response
6
Customer Approval & Initial
Payment Request
7
Customer Approval & Initial
Payment8Response
Final Callback to your App.
9

5
The table below describes the process for creating and verifying a Recurring Payment
Invoice:

Step Description

1 Your App sends an Invoice Creation request to Hubtel.

Hubtel performs authentication on request and sends response to your App with
2
a unique identifier (RecurringInvoiceId)

Hubtel sends verification OTP code to customer number to provide to third party
3
(your app).

Your App sends an Invoice Verification request to Hubtel with the customer OTP
4
code and unique identifier (RecurringInvoiceId)

5 Hubtel performs authentication on request and sends a response to Your App.

Hubtel goes to Mobile Money provider (with customer confirmation) to perform

6
the initial debit on the customer wallet.

After first payment is taken, a callback is sent to your App based on the provided
7
URL.

Whenever the invoice is due (scheduled time), a direct debit is made on the
8
customer mobile money wallet and a callback is sent to your App.

6
 4.0 API Reference

4.1 Create Invoice API

To initiate a Create Invoice transaction, make an HTTP POST to the below URL with the
required parameters:

API Endpoint https://rip.hubtel.com/api/proxy/{HubtelAccountNumber}/create-invoice

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The Date of invoice creation. This is a timestamp

orderDate String Mandatory of format MM/DD/YYYY HH:MM:SS
Eg: 11/01/2019 08:57:00

The date the recurring invoice is supposed to

end. This is a timestamp of format MM/DD/YYYY
invoiceEndDate String Optional
HH:MM:SS
Eg: 11/01/2019 08:57:00

The time of day when the debit would be taken

startTime String Mandatory whenever it is due. Format is HH:MM
Eg: 10:00

The interval between payments from the

customer. The possible options are:
“DAILY” – This means the customer will be
debited every day.
“WEEKLY” – This means the bsutomer will be
paymentInterval String Mandatory
debited every week (7 days)
“MONTHLY” – This means the customer will be
debited every month.
“QUARTERLY” – This means the customer will be
debited every Quarter (3 months).

7
 The customer’s mobile money number. This
customerMobileNumber String Mandatory
should be in the international format.
Eg: 233249111411

The payment option which the customer selects

paymentOption String Mandatory to pay for. Currently, the available options are:
“MobileMoney”.

The mobile money channel provider. Currently

the available channels are:

“mtn_gh_rec” – This is for payments using an

channel String Mandatory
MTN mobile money wallet.

“hubtel_gh” – This is for payments using a

hubtel wallet.

customerName String Optional The name of the customer.

The amount of money which will be debited

recurringAmount Double Mandatory from the customer wallet whenever the invoice
is due.

The total amount to be debited from the

totalAmount Double Mandatory customer wallet. Currently pass the same value
as the recurringAmount.

The amount to be debited from the customer

initialAmount Double Mandatory wallet for the first payment. This can be different
from the recurringAmount.

currency String Mandatory The currency of the transaction.

A URL used to receive the callback for successful

callbackUrl String Mandatory invoice creation and debit. All subsequent debit
callbacks are also sent to this same URL.

A brief description of the transaction. You can

description String Mandatory specify the use of the transaction in this:
Eg: “Extreme Gaming Service”

8
 Response Parameters:

Parameter Type Description

The unique response code on the status of the

ResponseCode String
transaction.
The message accompanying the response code. This
message Double
gives a brief description of the response from the API.
An object containing the required data response from
data Double
the Create Invoice API.
The unique ID used to identify a recurring invoice. This
recurringInvoiceId String ID will be used anytime a debit is done on the customer
wallet for this invoice.
The verification request ID which is to be used in the
requestId String
Verify Invoice request payload.
A 4 letter word prefix which is to be used together with
otpPrefix String the actual OTP code send to the customer in the Verify
Invoice request payload.

Sample Request
POST Endpoint HTTP/1.1
Host: BaseURL
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=
Cache-Control: no-cache
{
"orderDate":"11/05/2019 13:53:00",
"invoiceEndDate":"11/10/2019 13:53:00",
"description":"Extreme Gaming Service",
"startTime":"14:00",

9
 "paymentInterval":"DAILY",
"customerMobileNumber":"233246012176",
"paymentOption":"MobileMoney",
"channel":"mtn-gh",
"customerName":"Daniel Barnes",
"recurringAmount":0.10,
"totalAmount":0.10,
"initialAmount":0.10,
"currency":"GHS",
"callbackUrl":"https://webhook.site/b503d1a9-e726-f315254a6ede"
}

Sample Response
{
"responseCode": "0001",
"message": "Your request has been processed successfully.",
"data": {
"recurringInvoiceId": "0f84e20a2839482e807128e8c21d08d6",
"requestId": "a6487bc44eae44849fd80326a0dd802a",
"otpPrefix": "OQDM"
}
}

10
 4.2 Verify Invoice API

To send a Verify Invoice request, make an HTTP POST to the below URL with the required
parameters:

API Endpoint https://rip.hubtel.com/api/proxy/Verify-Invoice

Request Type POST

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The unique ID used to identify the recurring
recurringInvoiceId String Mandatory invoice being verified. It is taken from the create
invoice response.
The verification request ID which is received in
requestId String Mandatory
the create invoice response.
The OTP code used for verification. It consists of
the four letter otpPrefix received in the create
otpCode String Mandatory
invoice response and the four digit OTP code
sent to the customer. Eg: “RTYE-9231”

Response Parameters:

Parameter Type Description

The unique response code on the status of the

ResponseCode String
transaction.
The message accompanying the response code. This
message Double
gives a brief description of the response from the API.
An object containing the required data response from
data Double
the Verify Invoice API.
The unique ID used to identify the recurring invoice.
recurringInvoiceId String This ID will be used anytime a debit is done on the
customer wallet for this invoice.

11
 Sample Request
POST Endpoint HTTP/1.1
Host: BaseURL
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250fT3=
Cache-Control: no-cache
{
"recurringInvoiceId": "0f84e20a2839482e807128e8c21d08d6",
"requestId": "a6487bc44eae44849fd80326a0dd802a",
"otpCode": "OQDM-9514"
}

Sample Response
{
"responseCode": "0001",
"message": "Your request has been processed successfully. You will receive a
callback on the final status shortly.",
"data": {
"recurringInvoiceId": "0f84e20a2839482e807128e8c21d08d6"
}
}

4.3 Callback
When you provide a callback URL in your invoice creation request, you will be sent a
callback on the final state of the invoice as well as the final state of all payments made on
that invoice. This means the callback URL you specify should be implemented to listen for an
HTTP POST payload from Hubtel.

Recurring invoice creation requires a one-time approval from the customer in order for
money to move from the mobile money wallet into your Hubtel Account. As a result, invoice
creation has an asynchronous flow on all networks. This also means that the final status of

12
an invoice cannot be determined immediately after the request. It may take some time
(usually less than 10 minutes). So you're required to implement an HTTP callback on your
server to be able to receive final status of the transaction.

We recommend using service likes RequestBin or Webhook Tester to test your callback.
These services allow you to define temporary dummy endpoints which will show you the
requests and all the data you are receiving from Hubtel.

Sample Callback 1 (successful transaction)

{
"ResponseCode":"0000",
"Message": "success",
"Data": {
"OrderId": "1d0e06bc689c4de2bb87a54829a89640",
"Description": "My recurring service",
"RecurringInvoiceId": "8ae267e31af748d4934b0420be6f47f0",
"TransactionId": "5814152092296267804084",
"ClientReference": "8ae267e31af748d4934b0420be6f47f0",
"ExternalTransactionId": "5814152092296267804084",
"OrderDate": "2020-02-10 09:58:00",
"InvoiceEndDate":"2019-10-14 12:00:00",
"CustomerMobileNumber": "233246912184",
"Charges": 0.01,
"AmountAfterCharges": 0.19,
"AmountCharged": 0.20,
"Amount": 0.20,
"InitialAmount": 0.20,
"RecurringAmount": 0.10
}
}

13
Sample Callback 2 (failed transaction)
{
"ResponseCode":"2001",
"Message": "Failed",
"Data": {
"OrderId": "1d0e06bc689c4de2bb87a54829a89640",
"Description": "My recurring service",
"RecurringInvoiceId": "8ae267e31af748d4934b0420be6f47f0",
"TransactionId": "5814152092296267804084",
"ClientReference": "8ae267e31af748d4934b0420be6f47f0",
"ExternalTransactionId": null,
"OrderDate": "2020-02-10 09:58:00",
"InvoiceEndDate":"2019-10-14 12:00:00",
"CustomerMobileNumber": "233246912184",
"Charges": 0.01,
"AmountAfterCharges": 0.19,
"AmountCharged": 0.20,
"Amount": 0.20,
"InitialAmount": 0.20,
"RecurringAmount": 0.10
}
}

14
 4.4 Cancel Invoice API

To send a Cancel Invoice request, make an HTTP POST to the below URL with the required
parameters:
https://rip.hubtel.com/api/proxy/{HubtelAccountNumber}/cancel-
API Endpoint
invoice/{recurringInvoiceId}

Request Type DELETE

Content Type JSON

Request Parameters:

Parameter Type Requirement Description

The unique ID used to identify the recurring
recurringInvoiceId String Mandatory invoice being cancelled. It is taken from the
initial invoice creation process.

Response Parameters:

Parameter Type Description

ResponseCode String The unique response code on the status of the request.

The message accompanying the response code. This

message Double
gives a brief description of the response from the API.

Sample Request
DELETE /api/proxy/11920/Cancel-Invoice/0f84e20a2839482e807128e8c21d08d6
HTTP/1.1
Host: rip.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250f3=
Cache-Control: no-cache

15
 Sample Response
{
"responseCode": "0000",
"message": "Your request has been processed successfully"
}

5.0 API Response Codes

The Hubtel Recurring Payments API uses standard HTTP error reporting. Successful requests
return HTTP status codes in the 2xx. Failed requests return status codes in 4xx and 5xx.

Response Codes are included in the JSON response body, which contains information about
the error or status:

Response Code Description

Pending State. The transaction has been processed successfully. A callback

0001
will be sent on the final state.

0000 The transaction was successful. (final status)

The transaction failed. Either because the approval failed with the network
2001
provider or because the initial payment failed.

0005 There was an HTTP failure/exception when reaching the payment partner.

Validation Errors. Something is not quite right with this request. Please check
4000
and try again.

4101 Authorization for request is denied.

4103 Permission denied

16
Contact Us
Hubtel

63 Hotel Road
Accra - Ghana

Postal Code: GA098

Digital Address: GA-098-9573

P.O. Box CT 2156 Cantonments Accra, Ghana.

Telephone: (+233) 30 225 6859, 30 222 2081, 20 253 2273

Toll Free: 0800 222 081

General: [email protected]
Sales: [email protected]
Help: [email protected]

www.hubtel.com

17