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

## Endpoint

```http theme={null}
POST /v1/payments/ussd
```

## Authentication

Requires a Bearer token in the `Authorization` header.

```http theme={null}
Authorization: Bearer {{api_key}}
```

## Request Headers

| Header         | Value              |
| -------------- | ------------------ |
| `Accept`       | `application/json` |
| `Content-Type` | `application/json` |

## Request Body

| Field          | Type    | Required | Description                                                                                                        |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `amount`       | integer | required | Amount to charge in the specified currency                                                                         |
| `currency`     | string  | required | Currency code (e.g., `TZS`)                                                                                        |
| `phone_number` | string  | required | Customer's phone number (e.g., `07XXXXXXXX`)                                                                       |
| `metadata`     | object  | optional | Arbitrary key-value pairs for your reference,<br />maximum of 3 items with length of less that 100 characters each |

## Example Request

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

  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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',
          },
      },
  )
  ```
</CodeGroup>

## Request Body Example

```json theme={null}
{
  "amount": 1000,
  "currency": "TZS",
  "phone_number": "07XXXXXXXX",
  "metadata": {
    "order_id": "order_001",
    "customer_note": "Payment for services"
  }
}
```

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