Initiate USSD Push
curl --request POST \
--url https://pesahub.co/api/v1/payments/ussd \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"amount": 123,
"currency": "<string>",
"phone_number": "<string>",
"metadata": {}
}
'import requests
url = "https://pesahub.co/api/v1/payments/ussd"
payload = {
"amount": 123,
"currency": "<string>",
"phone_number": "<string>",
"metadata": {}
}
headers = {
"Authorization": "<authorization>",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: '<authorization>',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({amount: 123, currency: '<string>', phone_number: '<string>', metadata: {}})
};
fetch('https://pesahub.co/api/v1/payments/ussd', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://pesahub.co/api/v1/payments/ussd",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 123,
'currency' => '<string>',
'phone_number' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://pesahub.co/api/v1/payments/ussd"
payload := strings.NewReader("{\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://pesahub.co/api/v1/payments/ussd")
.header("Authorization", "<authorization>")
.header("Idempotency-Key", "<idempotency-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://pesahub.co/api/v1/payments/ussd")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "<string>",
"transaction_id": "<string>",
"transaction_channel": "<string>",
"amount": {
"value": 123,
"currency": "<string>"
},
"metadata": {}
}USSD Collection
Initiate USSD Push
Trigger a USSD push payment to the customer’s mobile wallet
POST
/
api
/
v1
/
payments
/
ussd
Initiate USSD Push
curl --request POST \
--url https://pesahub.co/api/v1/payments/ussd \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"amount": 123,
"currency": "<string>",
"phone_number": "<string>",
"metadata": {}
}
'import requests
url = "https://pesahub.co/api/v1/payments/ussd"
payload = {
"amount": 123,
"currency": "<string>",
"phone_number": "<string>",
"metadata": {}
}
headers = {
"Authorization": "<authorization>",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: '<authorization>',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({amount: 123, currency: '<string>', phone_number: '<string>', metadata: {}})
};
fetch('https://pesahub.co/api/v1/payments/ussd', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://pesahub.co/api/v1/payments/ussd",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 123,
'currency' => '<string>',
'phone_number' => '<string>',
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://pesahub.co/api/v1/payments/ussd"
payload := strings.NewReader("{\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://pesahub.co/api/v1/payments/ussd")
.header("Authorization", "<authorization>")
.header("Idempotency-Key", "<idempotency-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://pesahub.co/api/v1/payments/ussd")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 123,\n \"currency\": \"<string>\",\n \"phone_number\": \"<string>\",\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "<string>",
"transaction_id": "<string>",
"transaction_channel": "<string>",
"amount": {
"value": 123,
"currency": "<string>"
},
"metadata": {}
}Overview
Sends a USSD push prompt to the customer’s phone, asking them to authorize a payment from their mobile money wallet. Supports M-Pesa, Airtel Money, Halopesa, Mixx by Yas.Request Headers
string
required
Bearer token for authentication. Format:
Bearer <token>string
default:"application/json"
Expected response format. Use
application/json.string
default:"application/json"
Format of the request body. Use
application/json.string
required
A unique key to ensure idempotent requests.
Request Body
integer
required
Amount to charge in the specified currency, the minimum amount varies, the standard minimum is 1000 TZS, while some networks i.e Airtel Money may support as low as 500 TZS
string
required
Currency code (e.g.,
TZS)string
required
Customer’s phone number (e.g.,
07XXXXXXXX)object
Arbitrary key-value pairs for your reference. Maximum of 3 items, each less than 100 characters.
Example Request
curl -X POST https://pesahub.co/api/v1/payments/ussd \
-H "Authorization: Bearer {{api_key}}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H 'Idempotency-Key: <idempotency-key>'
-d '{
"amount": 1000,
"currency": "TZS",
"phone_number": "07XXXXXXXX",
"metadata": {
"order_id": "order_001",
"customer_note": "Payment for services"
}
}'
Response
boolean
required
Indicates whether the payment was initiated successfully.
string
required
A human-readable status message.
string
required
A unique UUID identifying the transaction.
string
required
The payment channel used (e.g.
AIRTEL-MONEY, HALOPESA).object
required
object
Additional key-value pairs passed during the request.
The customer will receive a USSD prompt on their phone to confirm the payment. Ensure the phone number matches an active mobile money account.