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

# Bank Payout

> Send money directly to a bank account

## Overview

The Bank Payout API allows you to transfer funds directly to a recipient's bank account. Use the **preview** endpoint to see fee breakdowns, **initiate** to execute the transfer, and **list** to retrieve past bank payouts.

***

## Preview Bank Payout

Calculate fees and validate recipient details before committing.

```http theme={null}
POST /v1/payouts/bank/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`)                                                                                    |
| `account_number`           | string        | required | Recipient's bank account number                                                                                |
| `bic`                      | string        | required | Bank Identifier Code (BIC/SWIFT) of the destination bank                                                       |
| `beneficiary.full_name`    | object.string | required | Recipient's full name as registered with the bank                                                              |
| `beneficiary.phone_number` | object.string | optional | 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/bank/preview \
    -H "Authorization: Bearer {{api_key}}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 10000,
      "currency": "TZS",
      "beneficiary": {
        "phone_number": "07XXXXXXXX",
        "full_name": "DEMO RECIPIENT"
      },
      "account_number": "XXXXXXXXXXXX",
      "bic": "NLCBTZTX",
      "metadata": {
        "order_id": "order_001",
        "notes": "Payment for services"
      }
    }'
  ```

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

***

## Initiate Bank Payout

Execute the bank transfer.

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

### Request Body

Same fields as the preview endpoint.

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://pesahub.test/api/v1/payouts/bank \
    -H "Authorization: Bearer {{api_key}}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 5000,
      "currency": "TZS",
      "beneficiary": {
        "phone_number": "07XXXXXXXX",
        "full_name": "DEMO RECIPIENT"
      },
      "account_number": "XXXXXXXXXXXX",
      "bic": "NLCBTZTX",
      "metadata": {
        "order_id": "order_001",
        "notes": "Payment for services"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://pesahub.test/api/v1/payouts/bank', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 5000,
      currency: 'TZS',
      beneficiary: {
        phone_number: '07XXXXXXXX',
        full_name: 'DEMO RECIPIENT',
      },
      account_number: 'XXXXXXXXXXXX',
      bic: 'NLCBTZTX',
      metadata: {
        order_id: 'order_001',
        notes: 'Payment for services',
      },
    }),
  });
  ```
</CodeGroup>

***

## List Bank Payouts

Retrieve a list of all bank payouts.

```http theme={null}
GET /v1/payouts/bank/list
```

### Example Request

```bash cURL theme={null}
curl -X GET https://pesahub.test/api/v1/payouts/bank/list \
  -H "Authorization: Bearer {{api_key}}" \
  -H "Accept: application/json"
```

<Tip>
  Always run a **preview** before initiating a bank payout to validate the BIC and account number are correct.
</Tip>