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

# Mobile Payout

> Send money directly to a mobile money wallet

## Overview

The Mobile Payout API lets you send funds directly to a recipient's mobile money wallet. Use the **preview** endpoint first to see fee breakdowns, then call **initiate** to execute the transfer.

***

## Preview Mobile Payout

Calculate fees and preview the payout before committing.

```http theme={null}
POST /v1/payouts/mobile/preview
```

### Authentication

```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 send in the specified currency                                                                           |
| `currency`     | string  | required | Currency code (e.g., `TZS`)                                                                                        |
| `phone_number` | string  | required | Recipient'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/payouts/mobile/preview \
    -H "Authorization: Bearer {{api_key}}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 1500,
      "currency": "TZS",
      "phone_number": "07XXXXXXXX",
      "metadata": {
        "order_id": "order_001",
        "note": "Payment for services"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://pesahub.test/api/v1/payouts/mobile/preview', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 1500,
      currency: 'TZS',
      phone_number: '07XXXXXXXX',
      metadata: {
        order_id: 'order_001',
        note: 'Payment for services',
      },
    }),
  });
  ```
</CodeGroup>

***

## Initiate Mobile Payout

Execute the mobile money transfer to the recipient.

```http theme={null}
POST /v1/payouts/mobile
```

### Request Body

Same fields as the preview endpoint.

| Field          | Type    | Required | Description                                                                                                    |
| -------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `amount`       | integer | required | Amount to send                                                                                                 |
| `currency`     | string  | required | Currency code (e.g., `TZS`)                                                                                    |
| `phone_number` | string  | required | Recipient's phone number                                                                                       |
| `metadata`     | object  | optional | Arbitrary key-value pairs for your reference,<br />max of 3 items with length of less than 100 characters each |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://pesahub.test/api/v1/payouts/mobile \
    -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",
        "note": "Payment for services"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://pesahub.test/api/v1/payouts/mobile', {
    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',
        note: 'Payment for services',
      },
    }),
  });
  ```
</CodeGroup>

<Tip>
  Always run a **preview** before initiating a payout to confirm fees and ensure the recipient details are correct.
</Tip>