> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pesahub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate USSD Push

> Trigger a USSD push payment to the customer's mobile wallet

## 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

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <token>`
</ParamField>

<ParamField header="Accept" default="application/json" type="string">
  Expected response format. Use `application/json`.
</ParamField>

<ParamField header="Content-Type" default="application/json" type="string">
  Format of the request body. Use `application/json`.
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  A unique key to ensure idempotent requests.
</ParamField>

## Request Body

<ParamField body="amount" type="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
</ParamField>

<ParamField body="currency" type="string" required>
  Currency code (e.g., `TZS`)
</ParamField>

<ParamField body="phone_number" type="string" required>
  Customer's phone number (e.g., `07XXXXXXXX`)
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs for your reference. Maximum of 3 items, each less than 100 characters.
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates whether the payment was initiated successfully.
</ResponseField>

<ResponseField name="message" type="string" required>
  A human-readable status message.
</ResponseField>

<ResponseField name="transaction_id" type="string" required>
  A unique UUID identifying the transaction.
</ResponseField>

<ResponseField name="transaction_channel" type="string" required>
  The payment channel used (e.g. `AIRTEL-MONEY`, `HALOPESA`).
</ResponseField>

<ResponseField name="amount" type="object" required>
  The transaction amount details.

  <Expandable title="amount properties">
    <ResponseField name="value" type="number">
      The numeric amount charged.
    </ResponseField>

    <ResponseField name="currency" type="string">
      The currency code (e.g. `TZS`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional key-value pairs passed during the request.
</ResponseField>

<Note>
  The customer will receive a USSD prompt on their phone to confirm the payment. Ensure the phone number matches an active mobile money account.
</Note>