Skip to main content

​
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, and TIPS Dynamic QR.

​
Endpoint

POST /v1/payments/ussd

​
Authentication

Requires a Bearer token in the Authorization header. 
Authorization: Bearer {{api_key}}

​
Request Headers

HeaderValue
Acceptapplication/json
Content-Typeapplication/json

​
Request Body

FieldTypeRequiredDescription
amountintegerrequiredAmount to charge in the specified currency
currencystringrequiredCurrency code (e.g., TZS)
phone_numberstringrequiredCustomer’s phone number (e.g., 07XXXXXXXX)
metadataobjectoptionalArbitrary key-value pairs for your reference,
maximum of 3 items with length of less that 100 characters each

​
Example Request

curl -X POST https://pesahub.test/api/v1/payments/ussd \
  -H "Authorization: Bearer {{api_key}}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "TZS",
    "phone_number": "07XXXXXXXX",
    "metadata": {
      "order_id": "order_001",
      "customer_note": "Payment for services"
    }
  }'

const response = await fetch('https://pesahub.test/api/v1/payments/ussd', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 1000,
    currency: 'TZS',
    phone_number: '07XXXXXXXX',
    metadata: {
      order_id: 'order_001',
      customer_note: 'Payment for services',
    },
  }),
});

const data = await response.json();

import requests

response = requests.post(
    'https://pesahub.test/api/v1/payments/ussd',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Accept': 'application/json',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 1000,
        'currency': 'TZS',
        'phone_number': '07XXXXXXXX',
        'metadata': {
            'order_id': 'order_001',
            'customer_note': 'Payment for services',
        },
    },
)

​
Request Body Example

{
  "amount": 1000,
  "currency": "TZS",
  "phone_number": "07XXXXXXXX",
  "metadata": {
    "order_id": "order_001",
    "customer_note": "Payment for services"
  }
}
The customer will receive a USSD prompt on their phone to confirm the payment. Ensure the phone number matches an active mobile money account.