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 support@hubtel.com.
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: info@hubtel.com
Sales: sales@hubtel.com
Help: support@hubtel.com
www.hubtel.com
17
