Skip to main content
POST
/
v3
/
payout
Create Payout
curl --request POST \
  --url https://service-sandbox.tazapay.com/v3/payout \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'
{
  "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"
        }
      }
    ]
  }
}

Authorizations

Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json
amount
integer<int32>
default:""
required

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

currency
string
required

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

purpose
enum<string>
required

Reason for payout. Click here for the detailed list.

Available options:
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
transaction_description
string
required

Additional Details for the payout

beneficiary_details
object

Comprehensive beneficiary information including personal details and destination

beneficiary
string

ID of an existing payout beneficiary

holding_currency
string

ISO 4217 standard, in uppercase. This is one of your balance currencies whose balance will fund the payout.

metadata
string<json>

Set of key-value pairs to attach to the payout object

type
enum<string>

Type of payout - local, swift, wallet, tazapay_account, local_payment_network

Available options:
local,
swift,
wallet,
local_payment_network,
tazapay_account
charge_type
enum<string>

For wire transfers only

Available options:
shared,
ours
statement_descriptor
string

Statement Descriptor for the payout

reference_id
string

Reference ID of the payout on your system

documents
object[]

Attach documents to the payout

on_behalf_of
string

ID of the entity the payout is created on behalf of

logistics_tracking_details
object[]

Logistics tracking details of the order. This is mandatory for CNY local payouts.

quote
string

Quote ID from the payout quote API

local
object

Local payout configuration object

items
object[]

List of invoice line items for the payout

Response

200

status
string
message
string
data
object

Contains detailed information about a payout object.