Create Payout

This lets you initiate a payout.

POST /v3/payout

Create Payout

cURL

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",
  "destination_fx_quote": "fx_d3inm6ami8u10oqfl",
  "logistics_tracking_details": [
    {
      "tracking_number": "1Z999AA10123456784",
      "logistics_provider": {
        "name": "UPS",
        "code": "UPS"
      }
    }
  ],
  "on_behalf_of": "ent_d3inm6ami8u10oqfm"
}
'

200

{
  "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": "[e-mail]",
      "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"
    },
    "logistics_tracking_details": [],
    "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": [],
    "destination_fx_quote": "fx_d4hu4786bhdq534ritlg",
    "reference_id": "INV-2024-0912",
    "statement_descriptor": "tzp*Consulting Fee",
    "status": "processing",
    "status_description": "",
    "tracking_details": null,
    "transaction_description": "Payment for consulting services",
    "type": "swift",
    "on_behalf_of": "",
    "logistic_tracking_details": []
  }
}

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

transaction_description · string · required

Additional Details for the payout

beneficiary_details · object

Beneficiary Details

Show child attributes

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

Show child attributes

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

Show child attributes

destination_fx_quote · string

ID of the quote to use locked exchange for conversion from payout to destination currency

quote · string

Quote ID from the payout quote API

local · object

Local payout configuration object

Show child attributes

Response

200

application/json

200

amount · number

Amount of the payout

balance_transaction · string

Id of the balance transaction object linked to this payout

beneficiary · string

Unique identifier of the beneficiary

beneficiary_details · object

Details of the payout beneficiary

Show child attributes

charge_type · string

Charge type for payout (e.g. ours/beneficiary)

created_at · string

Payout creation timestamp (ISO 8601 format)

currency · string

Currency of the payout

documents · any[]

Associated documents

holding_currency · string

Currency used for holding the funds before payout

holding_fx_transaction · object

FX transaction details for holding currency

Show child attributes

id · string

Unique payout ID

metadata · null

Metadata associated with payout

mt103 · string

SWIFT MT103 reference number

object · string

Type of object (payout)

payout_fx_transaction · object

FX transaction details for payout currency

Show child attributes

purpose · string

Purpose code or note for payout

reference_id · string

External reference ID for payout

statement_descriptor · string

Statement descriptor for transaction

status · string

Current payout status

status_description · string

Description of payout status

tracking_details · null

Tracking information if applicable

transaction_description · string

Description of the transaction

type · string

Type of payout (e.g. swift, ach)

on_behalf_of · string

Entity on whose behalf payout is made

quote · string · default: ""

Quote ID from the payout quote API

destination_fx_quote · string

ID of the quote to use locked exchange for conversion from payout to destination currency

confirmation_documents · string<json>[]

logistics_tracking_details · object[]

Logistics tracking details of the order

Show child attributes

available_balance · integer

Available balance in the account for processing payouts

is_balance_sufficient · boolean

Indicates whether the account has sufficient balance to process this payout

local · object

Local payout configuration object

Show child attributes