> ## 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.
# Create Payout
> This lets you initiate a payout.
## OpenAPI
````yaml post /v3/payout
openapi: 3.1.0
info:
title: sandbox
version: '3'
servers:
- url: https://service-sandbox.tazapay.com
security:
- sec0: []
paths:
/v3/payout:
post:
summary: Create Payout
description: This lets you initiate a payout.
operationId: create-payout
requestBody:
content:
application/json:
schema:
type: object
required:
- amount
- currency
- purpose
- transaction_description
properties:
amount:
type: integer
description: >-
Amount in cents. For example if you want to payout $10.12
pass 1012 as the value. For decimal handling for various
currencies, refer to the guide here
format: int32
default: ''
currency:
type: string
description: >-
ISO 4217 standard. This is the payout currency. The amount
will be in the payout currency
beneficiary_details:
$ref: '#/components/schemas/BeneficiaryDetails'
beneficiary:
type: string
description: ID of an existing payout beneficiary
holding_currency:
type: string
description: >-
ISO 4217 standard, in uppercase. This is one of your balance
currencies whose balance will fund the payout.
metadata:
type: string
description: Set of key-value pairs to attach to the payout object
format: json
type:
type: string
description: >-
Type of payout - local, swift, wallet, tazapay_account,
local_payment_network
enum:
- local
- swift
- wallet
- local_payment_network
- tazapay_account
charge_type:
type: string
description: For wire transfers only
enum:
- shared
- ours
purpose:
type: string
description: >-
Reason for payout. Click
[here](/Global-Money-Movement/payouts/purpose) for the
detailed list.
enum:
- PYR001
- PYR002
- PYR003
- PYR004
- PYR005
- PYR006
- PYR007
- PYR008
- PYR009
- PYR010
- PYR011
- PYR012
- PYR013
- PYR014
- PYR015
- PYR016
- PYR017
- PYR018
- PYR019
- PYR020
- PYR021
- PYR022
- PYR023
- PYR024
- PYR025
- PYR026
- PYR027
- PYR028
- PYR029
- PYR030
- PYR031
- PYR032
- PYR033
- PYR034
- PYR035
- PYR036
statement_descriptor:
type: string
description: Statement Descriptor for the payout
reference_id:
type: string
description: Reference ID of the payout on your system
transaction_description:
type: string
description: Additional Details for the payout
documents:
type: array
description: Attach documents to the payout
items:
properties:
type:
type: string
description: >-
A string mentioning the type of document. Supported
values: `invoice`, `other`, `contract`.
url:
type: string
description: Dynamically downloadable URL
required:
- type
- url
type: object
on_behalf_of:
type: string
description: ID of the entity the payout is created on behalf of
logistics_tracking_details:
type: array
description: >-
Logistics tracking details of the order. This is mandatory
for CNY local payouts.
items:
type: object
properties:
tracking_number:
type: string
logistics_provider:
type: object
properties:
name:
type: string
code:
type: string
quote:
type: string
description: Quote ID from the payout quote API
local:
type: object
description: Local payout configuration object
properties:
fund_transfer_network:
type: string
description: >-
The local fund transfer network to use for local payouts
(e.g., 'chats', 'fps', 'sepa', 'rtgs', 'ach', 'pix',
'npcc'). Fetch the entire list of available fund
transfer networks from the Payout
Bank Metadata API.
items:
type: array
description: >-
Optional list of invoice line items for the payout. Strongly
advised when purpose is PYR022 (General Goods Trades -
Offline trade) for CN-CNY local payouts to satisfy Chinese
regulatory requirements. Each item represents a goods entry
on the invoice.
items:
$ref: '#/components/schemas/PayoutItem'
examples:
Request Example:
value:
beneficiary: bnf_d3inm6ami8u10oqfh
beneficiary_details: null
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
logistics_tracking_details:
- tracking_number: 1Z999AA10123456784
logistics_provider:
name: UPS
code: UPS
on_behalf_of: ent_d3inm6ami8u10oqfm
items:
- name: Premium subscription (Jan 2026)
quantity: 1
amount: 50000
category: Goods
description: Subscription payout
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value:
status: success
message: ''
data:
amount: 100000
balance_transaction: btr_crv5u81h1l071n2fk1o0
beneficiary: bnf_crv5r71h1l071n2fjvog
beneficiary_details:
address:
city: test
country: US
line1: test
line2: test
postal_code: '10038'
state: test
destination: bnk_crv5r71gb6vrb4oj77kg
destination_details:
bank:
account_number: test
account_type: ''
bank_codes:
aba_code: test
swift_code: test
bank_name: city bank
branch_name: ''
country: US
currency: USD
firc_required: false
purpose_code: ''
type: bank
documents: []
email: test@example.com
name: test
phone:
calling_code: '1'
number: '12312312345'
tax_id: test
type: individual
charge_type: ours
created_at: '2024-10-03T09:08:48.467222Z'
currency: USD
documents: []
holding_currency: EUR
holding_fx_transaction:
exchange_rate: 1.059191
final:
amount: 100000
currency: USD
id: fx_crv5u80dj96g452dfr2g
initial:
amount: 94412
currency: EUR
object: fx_transaction
id: pot_crv5u81h1l071n2fk1ng
local:
fund_transfer_network: ach
metadata: null
mt103: ''
object: payout
payout_fx_transaction:
exchange_rate: 1
final:
amount: 100000
currency: USD
id: fx_crv5u80dj96g452dfr20
initial:
amount: 100000
currency: USD
object: fx_transaction
purpose: PYR001
quote: poq_crv5u81h1l071n2fk1n0
confirmation_documents: []
reference_id: INV-2024-0912
statement_descriptor: tzp*Consulting Fee
status: processing
status_description: ''
failure: null
tracking_details: null
transaction_description: Payment for consulting services
items:
- name: Premium subscription (Jan 2026)
quantity: 1
amount: 50000
category: Goods
description: Subscription payout
type: swift
on_behalf_of: ent_d68uqeuid0fvsnsfd1q0
logistics_tracking_details:
- tracking_number: '1263'
logistics_provider:
name: DHL Express
code: IO245
schema:
type: object
properties:
status:
type: string
message:
type: string
data:
$ref: '#/components/schemas/PayoutData'
'400':
description: Bad Request
content:
application/json:
examples:
Result:
value: '{}'
schema:
$ref: '#/components/schemas/ErrorResponse'
deprecated: false
components:
schemas:
BeneficiaryDetails:
type: object
description: >-
Comprehensive beneficiary information including personal details and
destination
required:
- name
- type
properties:
name:
type: string
description: Name of the beneficiary
maxLength: 140
email:
type: string
description: Email address of the beneficiary
type:
type: string
description: Type of beneficiary entity
enum:
- business
- individual
address:
$ref: '#/components/schemas/Address'
phone:
$ref: '#/components/schemas/Phone'
destination_details:
$ref: '#/components/schemas/DestinationDetails'
tax_id:
type: string
description: Tax ID of the beneficiary (e.g., CPF or CNPJ for Brazil)
national_identification_number:
type: string
description: National ID of the individual
registration_number:
type: string
description: Registration number of the business
date_of_birth:
type: string
description: Date of birth of individual (format DD-MM-YYYY)
nationality:
type: string
description: Nationality (ISO 3166-1 alpha-2 country code)
destination:
type: string
description: Destination identifier
documents:
type: array
description: Array of supporting documents
name_local:
type: string
description: Local name of the beneficiary
party_classification:
type: string
description: Party classification
status:
type: string
description: Status of the beneficiary
PayoutItem:
type: object
description: >-
Invoice line item for a payout. Required fields are name, quantity,
amount, and category. Currently only the "Goods" category is accepted.
Amounts are in minor units of the payout currency.
required:
- name
- quantity
- amount
- category
properties:
name:
type: string
description: Name of the goods item. Maximum 512 characters.
maxLength: 512
quantity:
type: integer
description: Number of units. Must be at least 1.
format: int32
minimum: 1
amount:
type: integer
description: >-
Unit price of the item in minor units of the payout currency (e.g.,
10000 = CNY 100.00). Must be greater than 0.
format: int64
minimum: 1
category:
type: string
description: Category of the item. Currently only "Goods" is accepted.
enum:
- Goods
description:
type: string
description: Optional free-text description of the item. Maximum 512 characters.
maxLength: 512
PayoutData:
type: object
description: Contains detailed information about a payout object.
properties:
amount:
type: integer
default: 0
description: Amount of the payout.
available_balance:
type: integer
description: >-
Available balance in the holding currency account after this payout
is processed.
balance_transaction:
type: string
description: Balance transaction ID associated with this payout.
beneficiary:
type: string
description: Beneficiary identifier.
beneficiary_details:
$ref: '#/components/schemas/BeneficiaryDetails'
charge_type:
type: string
description: Charge type of payout.
enum:
- ours
- shared
confirmation_documents:
type: array
description: List of documents confirming payout.
items:
type: object
properties:
key:
type: string
type:
type: string
value:
type: string
created_at:
type: string
description: Timestamp when payout was created.
currency:
type: string
description: Currency of the payout.
documents:
type: array
description: Documents associated with payout.
holding_currency:
type: string
description: Currency held for payout.
holding_fx_quote:
type: string
description: Holding FX quote ID.
holding_fx_transaction:
$ref: '#/components/schemas/FxTransaction'
id:
type: string
description: Unique payout identifier.
is_balance_sufficient:
type: boolean
description: >-
Indicates whether the account has sufficient balance to process this
payout.
local:
type: object
description: Local payout configuration.
properties:
fund_transfer_network:
type: string
description: Local fund transfer network used.
logistics_tracking_details:
type: array
description: Logistics tracking details. Mandatory for CNY local payouts.
items:
type: object
properties:
tracking_number:
type: string
logistics_provider:
type: object
properties:
name:
type: string
code:
type: string
metadata:
$ref: '#/components/schemas/Metadata'
mt103:
type: string
description: SWIFT MT103 details if available.
object:
type: string
description: Type of object (payout).
on_behalf_of:
type: string
description: Entity on whose behalf the payout is made.
payout_fx_transaction:
$ref: '#/components/schemas/FxTransaction'
payout_quote:
type: string
description: Payout quote reference.
purpose:
type: string
description: Purpose code for the payout.
quote:
type: string
description: Quote ID from the payout quote API.
reference_id:
type: string
description: External reference ID for payout.
reversal_balance_transaction:
type: string
description: >-
Id of the reverse balance transaction linked to this payout. Only
present when status is 'reversed'.
reversal_payout_fx_transaction:
$ref: '#/components/schemas/FxTransaction'
statement_descriptor:
type: string
description: Statement descriptor for the payout.
status:
type: string
description: Current status of the payout.
status_description:
type: string
description: Detailed status description.
failure:
type: object
nullable: true
description: >-
Failure details of the payout. Only present when the payout has
failed.
properties:
code:
type: string
description: >-
Error code indicating the reason for the payout failure. Refer
to the failure code list
[**here**](/API-Reference/appendix/payout-failure-reasons-updated).
description:
type: string
description: Human-readable description of the failure reason.
tracking_details:
type: object
description: Tracking details of payout.
properties:
tracking_number:
type: string
description: Tracking number (UETR, UTR, transaction hash, etc.)
tracking_type:
type: string
description: Tracking type used for payout.
enum:
- uetr
- utr
- transaction_hash
transaction_description:
type: string
description: Description or memo for the payout transaction.
items:
type: array
description: List of invoice line items for the payout
items:
$ref: '#/components/schemas/PayoutItem'
type:
type: string
description: Type of payout.
enum:
- swift
- local
- wallet
- local_payment_network
- tazapay_account
ErrorResponse:
type: object
description: Standard error response structure
properties:
status:
type: string
enum:
- error
description: Always 'error' for error responses
message:
type: string
description: High-level error message
errors:
type: array
description: Array of detailed error objects
items:
type: object
properties:
code:
type: integer
description: Specific error code
message:
type: string
description: Detailed error message
remarks:
type: string
description: Additional context or suggestions for resolution
Address:
type: object
description: Address details
properties:
line1:
type: string
description: Address Line 1
line2:
type: string
description: Address Line 2
city:
type: string
description: Address city
state:
type: string
description: Address state
country:
type: string
description: Address country (ISO 3166-1 alpha-2 country code)
postal_code:
type: string
description: Postal Code
Phone:
type: object
description: Phone contact details
properties:
calling_code:
type: string
description: >-
Calling country code (for example, '1' for United States, '91' for
India)
number:
type: string
description: Phone Number
DestinationDetails:
type: object
description: >-
Destination details for beneficiary payouts (discriminated union based
on type)
required:
- type
properties:
type:
type: string
description: Type of destination
enum:
- bank
- wallet
- local_payment_network
- tazapay_account
bank:
$ref: '#/components/schemas/Bank'
wallet:
$ref: '#/components/schemas/Wallet'
local_payment_network:
$ref: '#/components/schemas/LocalPaymentNetwork'
tazapay_account:
$ref: '#/components/schemas/TazapayAccount'
FxTransaction:
type: object
description: Details of an FX conversion transaction
properties:
exchange_rate:
type: number
description: FX exchange rate applied
final:
type: object
description: Final amount and currency after FX conversion
properties:
amount:
type: number
description: Final amount after FX conversion
currency:
type: string
description: Currency of the final amount
id:
type: string
description: FX transaction ID
initial:
type: object
description: Initial amount and currency before FX conversion
properties:
amount:
type: number
description: Initial amount before FX conversion
currency:
type: string
description: Currency of the initial amount
object:
type: string
description: Object type (fx_transaction)
Metadata:
type: object
description: Custom metadata key-value pairs attached to the object
additionalProperties:
type: string
nullable: true
Bank:
type: object
description: Bank account details
properties:
account_number:
type: string
description: Bank Account Number. Either account_number or IBAN is mandatory
iban:
type: string
description: IBAN. Either account_number or iban is mandatory
bank_name:
type: string
description: Name of the bank
branch_name:
type: string
description: Name of the branch
country:
type: string
description: Two-letter country code (ISO 3166-1 alpha-2)
currency:
type: string
description: Three-letter ISO currency code, in uppercase
purpose_code:
type: string
description: Purpose Code for INR bank accounts
bank_codes:
$ref: '#/components/schemas/BankCodes'
firc_required:
type: boolean
description: Pass true if you want FIRC for a payout to India
account_type:
type: string
description: Type of bank account
enum:
- savings
- checking
- payment
account_holder_name:
type: string
description: Name of the account holder
transfer_type:
type: string
description: Type of transfer (e.g., local, SWIFT)
Wallet:
type: object
description: Crypto wallet destination details
required:
- deposit_address
- type
- currency
properties:
deposit_address:
type: string
description: Blockchain wallet address
type:
type: string
description: >-
Type of blockchain wallet (e.g., ethereum,
bitcoin_lightning_network). Use `bitcoin_lightning_network` for BTC
currency only.
enum:
- ethereum
- tron
- polygon
- solana
- bitcoin_lightning_network
currency:
type: string
description: Cryptocurrency code (e.g., USDC, BTC, ETH)
hosted:
type: string
description: Whether wallet is hosted/custodial
enum:
- 'yes'
- 'no'
vasp_name:
type: string
description: Virtual Asset Service Provider name (required for hosted wallets)
vasp_website:
type: string
description: VASP website URL (required for hosted wallets)
LocalPaymentNetwork:
type: object
description: Local payment network destination details (e.g., PIX, UPI, PromptPay)
required:
- type
- deposit_key
properties:
type:
type: string
description: >-
Type of local payment network (e.g., pix_brl, upi_inr,
promptpay_thb)
deposit_key_type:
type: string
description: >-
Type of the deposit key (conditionally mandatory depending on
network type)
deposit_key:
type: string
description: >-
Deposit key for the local payment network (e.g., PIX key, UPI
handle)
currency:
type: string
description: Currency code for the local payment network
TazapayAccount:
type: object
description: Tazapay account destination details
required:
- deposit_address
properties:
deposit_address:
type: string
description: Tazapay account deposit address (format - xxxxx@tzp)
BankCodes:
type: object
description: Bank specific identification codes
properties:
swift_code:
type: string
description: SWIFT Code
bic_code:
type: string
description: Bank Identifier Code (BIC)
ifsc_code:
type: string
description: IFS Code
aba_code:
type: string
description: ABA / Routing Number
sort_code:
type: string
description: SORT Code
branch_code:
type: string
description: Branch Code
bsb_code:
type: string
description: BSB Code
bank_code:
type: string
description: Bank Code
cnaps:
type: string
description: CNAPS
securitySchemes:
sec0:
type: http
scheme: basic
````