Creating a Payout via API

Endpoint

POST /v3/payout

Authorization

string

required

Basic authentication header of the form Basic <encoded-value> where <encoded-value> is the Base64 encoding of username:password.

Request Body

amount

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.

currency

string

required

ISO 4217 standard. This is the payout currency. The amount will be in the payout currency.

purpose

string

required

Reason for payout. See the full list of supported purpose codes.Supported values: PYR001 – PYR036

transaction_description

string

required

Additional details for the payout.

beneficiary

string

ID of an existing payout beneficiary. Use this instead of beneficiary_details if the beneficiary is already saved.

beneficiary_details

object

Inline beneficiary information. Use this when not referencing a saved beneficiary.

Show beneficiary_details fields

name

string

required

Name of the beneficiary. Max 140 characters.

type

string

required

Type of beneficiary entity. Supported values: business, individual.

string

Email address of the beneficiary.

tax_id

string

Tax ID of the beneficiary (e.g., CPF or CNPJ for Brazil).

national_identification_number

string

National ID of the individual.

registration_number

string

Registration number of the business.

date_of_birth

string

Date of birth of individual. Format: DD-MM-YYYY.

nationality

string

Nationality as ISO 3166-1 alpha-2 country code.

name_local

string

Local name of the beneficiary.

destination

string

Destination identifier.

destination_details

object

Bank account or wallet destination details.

address

object

Address of the beneficiary.

phone

object

Phone number of the beneficiary.

documents

array

Array of supporting documents.

holding_currency

string

ISO 4217 standard, uppercase. The balance currency used to fund the payout.

type

string

Type of payout. Supported values: local, swift, wallet, local_payment_network, tazapay_account.

charge_type

string

For wire transfers only. Supported values: shared, ours.

quote

string

Quote ID from the payout quote API.

local

object

Local payout configuration.

Show local fields

fund_transfer_network

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.

reference_id

string

Reference ID of the payout on your system.

statement_descriptor

string

Statement descriptor for the payout.

on_behalf_of

string

ID of the entity the payout is created on behalf of.

metadata

string

Set of key-value pairs to attach to the payout object (JSON string format).

documents

array

Attach documents to the payout.

Show document fields

type

string

required

Type of document. Supported values: invoice, other, contract.

url

string

required

Dynamically downloadable URL of the document.

logistics_tracking_details

array

Logistics tracking details. Mandatory for CNY local payouts.

Show logistics fields

tracking_number

string

Shipment tracking number.

logistics_provider

object

Logistics provider details with name and code.

items

array

Invoice line items. Strongly advised when purpose is PYR022 for CN-CNY local payouts.

Show item fields

name

string

Item name.

quantity

integer

Item quantity.

amount

integer

Item amount in cents.

Example Request

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

{
  "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": ""
  }
}

Overview

Coverage

Payout Network