logo

Hubtel API Documentation (1.0.0)

E-mail: support@hubtel.com URL: https://developers.hubtel.com/ Terms of Service

The following documentation presents comprehensive resources to help developers integrate with Hubtel.
With these APIs, you can process online payments and connect to customers via SMS.

Please note that all endpoints on this page are rate-limited, allowing up to 5 requests per minute.
Further, all recipients (for SMS, send/request money) defaults to the owner of the API keys

Live endpoints (without stated restrictions) are available on the developer's portal

Authentication

basic_auth

You need to authenticate every request you make mainly using basic authentication.
Visit here, click on 'Create Keys'; a ClientID and Client Secret will be generated for you.
When using the 'Try It' panel, input ClientID as username and Client Secret as password.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

SMS

API to send SMS.

quick send

This endpoint uses a GET verb to send SMS. No authorization is required in the header

Request
query Parameters
clientid
string

Your API Client ID

clientsecret
string

Your API Client secret

from
string

Must be 11 alpha-numeric characters or less; subject to approval by Hubtel.

to
string

The recipient's telephone number. Must be full international format (E164)

content
string

The message content; preferably less than 160 characters for best experience

Responses
201

Success

400

Bad Request

404

Not Found

429

Bad Request

500

Internal Server Error

get/send
Request samples
curl -i -X GET \
  'https://devp-sms03726-api.hubtel.com/v1/messages/send?clientid=string&clientsecret=string&from=string&to=string&content=string'
Response samples
application/json
{
  • "message": "string",
  • "responseCode": "string",
  • "data": {
    }
}

regular

This endpoint uses a POST verb to send SMS. Authorization is required in the header.

Request
Security:
basic_auth
Request Body schema: application/json
from
string

Must be 11 alpha-numeric characters or less; subject to approval by Hubtel.

to
string

The recipient's telephone number. Must be full international format (E164)

content
string

The message content; preferably less than 160 characters for best experience

Responses
201

Success

400

Bad Request

401

Bad Request

404

Not Found

429

Bad Request

500

Internal Server Error

post/send
Request samples
application/json
{
  • "from": "MySenderId",
  • "to": "string",
  • "content": "hello world"
}
Response samples
application/json
{
  • "message": "string",
  • "responseCode": "string",
  • "data": {
    }
}

query final status

This endpoint uses a GET verb to query the final status of a previously sent SMS. Authorization is required in the header

Request
Security:
basic_auth
path Parameters
messageId
required
string

The message ID. This must be valid and not null

Responses
201

Success

404

Bad Request

get/messages/{messageId}
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://devp-sms03726-api.hubtel.com/v1/messages/{messageId}'
Response samples
application/json
{
  • "message": "string",
  • "responseCode": "string",
  • "data": {
    }
}

OTP

This service enables you to verify your users via One-Time-Password.
This is especially useful for authentication.

When implemented, Hubtel generates 3 tokens: RequestId (an identifier for your OTP session), Prefix (a 4 character phrase) and Code (the 4 digit code that will only be delivered to your user via SMS).
Your system is expected to verify the user by presenting these 3 tokens.
You may resend an OTP using the same RequestID.

As a fallback option, Hubtel provides a USSD option to view the Code, in cases where SMS delivery fails.
The user is expected to dial the USSD code using the same phone number that should have received the SMS. The code is "711777#"

send OTP

This endpoint sends an OTP to the recipient.

Request
Security:
basic_auth
Request Body schema: application/json
senderId
string

Must be 11 alpha-numeric characters or less; subject to approval by Hubtel.

phoneNumber
string

The recipient's telephone number. Must be full international format (E164)

countryCode
string

Must be a valid ISO 3166-1 alpha-2 country code

Responses
200

Success

400

Bad Request

500

Server Error

post/otp/send
Request samples
application/json
{
  • "senderId": "MySenderId",
  • "phoneNumber": "string",
  • "countryCode": "GH"
}
Response samples
application/json
{
  • "message": "string",
  • "code": "string",
  • "data": {
    }
}

verify OTP

This endpoint verifies an OTP.

Request
Security:
basic_auth
Request Body schema: application/json
requestId
string

The requestId from /send/otp endpoint

prefix
string

The prefix from /send/otp endpoint

code
string

The 4-digit code from your user

Responses
200

Success

400

Bad Request

500

Server Error

post/otp/verify
Request samples
application/json
{
  • "requestId": "string",
  • "prefix": "string",
  • "code": "string"
}
Response samples
application/json
{
  • "errors": [
    ],
  • "code": "string",
  • "status": "string",
  • "message": "string",
  • "data": { }
}

resend OTP

This endpoint re-sends a previously issued OTP to your user. A common use case may be when the SMS delivery delays significantly.

Request
Security:
basic_auth
Request Body schema: application/json
requestId
string

Must be a valid, previuosly issued requestId from /send/otp

Responses
200

Success

400

Bad Request

500

Server Error

post/otp/resend
Request samples
application/json
{
  • "requestId": "string"
}
Response samples
application/json
{
  • "message": "string",
  • "code": "string",
  • "data": {
    }
}

Request Money

API to request money.

single request

This endpoint generates a URL ('paylinkUrl' in the response body) that can be used to receive money from a single customer into your Hubtel account for onward settlement.

Request
Security:
basic_auth
path Parameters
mobileNumber
required
string

Must be a valid E164 format

Request Body schema: application/json
amount
number <double> [ 0 .. 30000 ]

Indicates how much you intend to receive. If amount=0, the customer decides on how much to pay

title
required
string

This appears as the title on the redirected web page

description
required
string

This appears as the sub-title on the redirected web page

clientReference
required
string

A unique string that should be used by your application to track progress of payment

callbackUrl
required
string <uri>

Must be a well-formed HTTP URL that will be triggered with callback data after successful payment

cancellationUrl
string <uri>

Must be a well-formed web URL that will be triggered as a redirect after customer decides to cancel payment request

returnUrl
string <uri>

Must be a well-formed web URL that will be triggered as a redirect after successful payment

logo
string <uri>

Must be a PNG/JPEG image for best appearance

Responses
201

Success

400

Bad Request

424

Failed Dependency

500

Server Error

post/request-money/{mobileNumber}
Request samples
application/json
{}
Response samples
application/json
{
  • "message": "string",
  • "code": "string",
  • "data": {
    }
}

bulk request

This endpoint generates a URL ('paylinkUrl' in the response body) that can be used to receive money from multiple customers into your Hubtel account for onward settlement.

Request
Security:
basic_auth
Request Body schema: application/json
amount
number <double> [ 0 .. 30000 ]

Indicates how much you intend to receive. If amount=0, the customer decides on how much to pay

title
required
string

This appears as the title on the redirected web page

description
required
string

This appears as the sub-title on the redirected web page

clientReference
required
string

A unique string that should be used by your application to track progress of payment

callbackUrl
required
string <uri>

Must be a well-formed HTTP URL that will be triggered with callback data after successful payment

cancellationUrl
string <uri>

Must be a well-formed web URL that will be triggered as a redirect after customer decides to cancel payment request

returnUrl
string <uri>

Must be a well-formed web URL that will be triggered as a redirect after successful payment

logo
string <uri>

Must be a PNG/JPEG image for best appearance

audience
Array of strings

Your list of phone numbers, in E164 format. Should not exceed 10,000

Responses
201

Success

400

Bad Request

424

Failed Dependency

500

Server Error

post/request-money/bulk
Request samples
application/json
{}
Response samples
application/json
{
  • "message": "string",
  • "code": "string",
  • "data": {
    }
}

webhookWebhook

Callback sent from Hubtel after money is paid.

Request
Request Body schema: application/json
message
string
responseCode
string
object (ReceiveMoneyCallbackResponseData)
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "message": "string",
  • "responseCode": "string",
  • "data": {
    }
}

Send Money

API to send money.

single request

This endpoint notifies a single customer about a pending withdrawal. After funds are withdrawn successfully, a callback is sent to your 'callbackUrl'

Request
Security:
basic_auth
path Parameters
mobileNumber
required
string

Must be a valid E164 format

Request Body schema: application/json
amount
number <double> [ 0.5 .. 30000 ]

Indicates how much you intend to send.

title
required
string

This appears as the title on the redirected web page

description
required
string

This appears as the sub-title on the redirected web page

clientReference
required
string

A unique string that should be used by your application to track progress of payment

callbackUrl
required
string <uri>

Must be a well-formed HTTP URL that will be triggered with callback data after successful payment

cancellationUrl
string <uri>

Must be a well-formed web URL that will be triggered as a redirect after customer decides to cancel

returnUrl
string <uri>

Must be a well-formed web URL that will be triggered as a redirect after successful payment

logo
string <uri>

Must be a PNG/JPEG image for best appearance

Responses
201

Success

400

Bad Request

424

Failed Dependency

500

Server Error

post/send-money/{mobileNumber}
Request samples
application/json
{}
Response samples
application/json
{
  • "message": "string",
  • "code": "string",
  • "data": {
    }
}

bulk request

This endpoint notifies list of customers about a pending withdrawal. After they withdraw funds successfully, a callback is sent to your 'callbackUrl'

Request
Security:
basic_auth
Request Body schema: application/json
amount
number <double> [ 0.5 .. 30000 ]

Indicates how much you intend to send to all recipients

title
required
string

This appears as the title on the redirected web page

description
required
string

This appears as the sub-title on the redirected web page

clientReference
required
string

A unique string that should be used by your application to track progress of payment

callbackUrl
required
string <uri>

Must be a well-formed HTTP URL that will be triggered with callback data after successful payment

cancellationUrl
string <uri>

Must be a well-formed web URL that will be triggered as a redirect after customer decides to cancel

returnUrl
string <uri>

Must be a well-formed web URL that will be triggered as a redirect after successful payment

logo
string <uri>

Must be a PNG/JPEG image for best appearance

audience
Array of strings

Your list of phone numbers, in E164 format. Should not exceed 10,000

Responses
201

Success

400

Bad Request

424

Failed Dependency

500

Server Error

post/send-money/bulk
Request samples
application/json
{}
Response samples
application/json
{
  • "message": "string",
  • "code": "string",
  • "data": {
    }
}

webhookWebhook

Callback sent from Hubtel when money is withdrawn.

Request
Request Body schema: application/json
message
string
responseCode
string
object (SendMoneyCallbackResponseData)
Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json
{
  • "message": "string",
  • "responseCode": "string",
  • "data": {
    }
}