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

<Note>
  Bank payout is currently restricted to 1,000,000 TZS in a single transaction
</Note>

***

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

## Preview Bank Payout

Calculate fees and validate recipient details before committing.

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

### Request Body

<ParamField body="amount" type="integer" required>
  Amount to send in the specified currency
</ParamField>

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

<ParamField body="account_number" type="string" required>
  Recipient's bank account number
</ParamField>

<ParamField body="bic" type="string" required>
  Bank Identifier Code (BIC/SWIFT) of the destination bank
</ParamField>

<ParamField body="beneficiary" type="object" required>
  Recipient details

  <Expandable title="beneficiary">
    <ParamField body="full_name" type="string" required>
      Recipient's full name as registered with the bank
    </ParamField>

    <ParamField body="phone_number" type="string">
      Recipient's phone number
    </ParamField>
  </Expandable>
</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/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"
      }
    }'
  ```
</CodeGroup>

***

## Initiate Bank Payout

Execute the bank transfer.

### Request Body

Same fields as the preview endpoint.

### Response

<ResponseField name="success" type="boolean">
  Indicates whether the bank payout was successful.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="balance" type="object">
  Updated account balance after the payout.

  <Expandable title="balance">
    <ResponseField name="current" type="number">
      Current available balance.
    </ResponseField>

    <ResponseField name="reserved" type="number">
      Reserved (held) balance.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="transaction_id" type="string">
  Unique identifier for the transaction.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the payout. Example: `initiated`.
</ResponseField>

<ResponseField name="amount" type="object">
  Details about the payout amount.

  <Expandable title="amount">
    <ResponseField name="value" type="number">
      The payout amount.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code. Example: `TZS`.
    </ResponseField>

    <ResponseField name="fee" type="number">
      Transaction fee applied.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="bank" type="object">
  Bank account details used for the payout.

  <Expandable title="bank">
    <ResponseField name="account_number" type="string">
      The recipient's bank account number.
    </ResponseField>

    <ResponseField name="bic" type="string">
      Bank Identifier Code (BIC/SWIFT) of the recipient's bank.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata attached to the payout.

  <Expandable title="metadata">
    <ResponseField name="order_id" type="number">
      Associated order identifier.
    </ResponseField>

    <ResponseField name="notes" type="string">
      Optional notes for the payout.
    </ResponseField>
  </Expandable>
</ResponseField>

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