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

# Creating a Payout via API

> Create payouts programmatically using the Tazapay API

## Endpoint

```
POST /v3/payout
```

***

## Authorization

<ParamField header="Authorization" type="string" required>
  Basic authentication header of the form `Basic <encoded-value>` where `<encoded-value>` is the Base64 encoding of `username:password`.
</ParamField>

***

## Request Body

<ParamField body="amount" type="integer" required>
  Amount in cents. For example, to payout \$10.12 pass `1012`. For decimal handling for various currencies, refer to the [Decimal Currencies guide](/api-reference/appendix/decimal-currencies).
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 standard. This is the payout currency. The amount will be in the payout currency.
</ParamField>

<ParamField body="purpose" type="string" required>
  Reason for payout. See the [full list of supported purpose codes](/payouts/payout-network/purpose).

  Supported values: `PYR001` – `PYR036`
</ParamField>

<ParamField body="transaction_description" type="string" required>
  Additional details for the payout.
</ParamField>

<ParamField body="beneficiary" type="string">
  ID of an existing payout beneficiary. Use this instead of `beneficiary_details` if the beneficiary is already saved.
</ParamField>

<ParamField body="beneficiary_details" type="object">
  Inline beneficiary information. Use this when not referencing a saved beneficiary.

  <Expandable title="beneficiary_details fields">
    <ParamField body="name" type="string" required>
      Name of the beneficiary. Max 140 characters.
    </ParamField>

    <ParamField body="type" type="string" required>
      Type of beneficiary entity. Supported values: `business`, `individual`.
    </ParamField>

    <ParamField body="email" type="string">
      Email address of the beneficiary.
    </ParamField>

    <ParamField body="tax_id" type="string">
      Tax ID of the beneficiary (e.g., CPF or CNPJ for Brazil).
    </ParamField>

    <ParamField body="national_identification_number" type="string">
      National ID of the individual.
    </ParamField>

    <ParamField body="registration_number" type="string">
      Registration number of the business.
    </ParamField>

    <ParamField body="date_of_birth" type="string">
      Date of birth of individual. Format: `DD-MM-YYYY`.
    </ParamField>

    <ParamField body="nationality" type="string">
      Nationality as ISO 3166-1 alpha-2 country code.
    </ParamField>

    <ParamField body="name_local" type="string">
      Local name of the beneficiary.
    </ParamField>

    <ParamField body="destination" type="string">
      Destination identifier.
    </ParamField>

    <ParamField body="destination_details" type="object">
      Bank account or wallet destination details.
    </ParamField>

    <ParamField body="address" type="object">
      Address of the beneficiary.
    </ParamField>

    <ParamField body="phone" type="object">
      Phone number of the beneficiary.
    </ParamField>

    <ParamField body="documents" type="array">
      Array of supporting documents.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="holding_currency" type="string">
  ISO 4217 standard, uppercase. The balance currency used to fund the payout.
</ParamField>

<ParamField body="type" type="string">
  Type of payout. Supported values: `local`, `swift`, `wallet`, `local_payment_network`, `tazapay_account`.
</ParamField>

<ParamField body="charge_type" type="string">
  For wire transfers only. Supported values: `shared`, `ours`.
</ParamField>

<ParamField body="quote" type="string">
  Quote ID from the [payout quote API](/payouts/managing-fx/creating-a-quote-and-then-attaching-it-to-a-payout).
</ParamField>

<ParamField body="local" type="object">
  Local payout configuration.

  <Expandable title="local fields">
    <ParamField body="fund_transfer_network" type="string">
      The local fund transfer network to use (e.g., `chats`, `fps`, `sepa`, `rtgs`, `ach`, `pix`, `npcc`). Fetch available networks from the [Payout Bank Metadata API](/api-reference/tazapay-api/payout-bank).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reference_id" type="string">
  Reference ID of the payout on your system.
</ParamField>

<ParamField body="statement_descriptor" type="string">
  Statement descriptor for the payout.
</ParamField>

<ParamField body="on_behalf_of" type="string">
  ID of the entity the payout is created on behalf of.
</ParamField>

<ParamField body="metadata" type="string">
  Set of key-value pairs to attach to the payout object (JSON string format).
</ParamField>

<ParamField body="documents" type="array">
  Attach documents to the payout.

  <Expandable title="document fields">
    <ParamField body="type" type="string" required>
      Type of document. Supported values: `invoice`, `other`, `contract`.
    </ParamField>

    <ParamField body="url" type="string" required>
      Dynamically downloadable URL of the document.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="logistics_tracking_details" type="array">
  Logistics tracking details. Mandatory for CNY local payouts.

  <Expandable title="logistics fields">
    <ParamField body="tracking_number" type="string">
      Shipment tracking number.
    </ParamField>

    <ParamField body="logistics_provider" type="object">
      Logistics provider details with `name` and `code`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="items" type="array">
  Invoice line items. Strongly advised when `purpose` is `PYR022` for CN-CNY local payouts.

  <Expandable title="item fields">
    <ParamField body="name" type="string">Item name.</ParamField>
    <ParamField body="quantity" type="integer">Item quantity.</ParamField>
    <ParamField body="amount" type="integer">Item amount in cents.</ParamField>
    <ParamField body="category" type="string">Item category.</ParamField>
    <ParamField body="description" type="string">Item description.</ParamField>
  </Expandable>
</ParamField>

***

## Example Request

```json theme={null}
{
  "beneficiary": "bnf_d3inm6ami8u10oqfh",
  "amount": 50000,
  "currency": "HKD",
  "holding_currency": "USD",
  "type": "local",
  "charge_type": "shared",
  "purpose": "PYR003",
  "reference_id": "HK-PAY-2024-156",
  "transaction_description": "Supplier payment for electronics order",
  "statement_descriptor": "Supplier Payment",
  "documents": [],
  "local": {
    "fund_transfer_network": "chats"
  },
  "quote": "poq_d3inm6ami8u10oqfk",
  "on_behalf_of": "ent_d3inm6ami8u10oqfm",
  "logistics_tracking_details": [
    {
      "tracking_number": "1Z999AA10123456784",
      "logistics_provider": { "name": "UPS", "code": "UPS" }
    }
  ],
  "items": [
    {
      "name": "Premium subscription (Jan 2026)",
      "quantity": 1,
      "amount": 50000,
      "category": "Goods",
      "description": "Subscription payout"
    }
  ]
}
```

***

## Example Response

```json theme={null}
{
  "status": "success",
  "message": "",
  "data": {
    "id": "pot_crv5u81h1l071n2fk1ng",
    "object": "payout",
    "amount": 100000,
    "currency": "USD",
    "holding_currency": "EUR",
    "type": "swift",
    "status": "processing",
    "status_description": "",
    "purpose": "PYR001",
    "reference_id": "INV-2024-0912",
    "statement_descriptor": "tzp*Consulting Fee",
    "transaction_description": "Payment for consulting services",
    "charge_type": "ours",
    "quote": "poq_crv5u81h1l071n2fk1n0",
    "on_behalf_of": "ent_d68uqeuid0fvsnsfd1q0",
    "balance_transaction": "btr_crv5u81h1l071n2fk1o0",
    "created_at": "2024-10-03T09:08:48.467222Z",
    "holding_fx_transaction": {
      "id": "fx_crv5u80dj96g452dfr2g",
      "object": "fx_transaction",
      "exchange_rate": 1.059191,
      "initial": { "amount": 94412, "currency": "EUR" },
      "final": { "amount": 100000, "currency": "USD" }
    },
    "local": {
      "fund_transfer_network": "ach"
    },
    "beneficiary": "bnf_crv5r71h1l071n2fjvog",
    "documents": [],
    "confirmation_documents": [],
    "failure": null,
    "tracking_details": null,
    "metadata": null,
    "mt103": ""
  }
}
```