The request body has only two fields — name and payload — but payload is where all the
recipient details go, and it is a free-form map, so it cannot be listed as a fixed set of
fields here.
What goes into payload: the destination.* fields of the transfer create body, written
as flat dot-notation keys. The accepted keys differ per payout method and provider, so the
authoritative list for a given route is the quote requirements endpoint
(GET /api/v2/transfers/quotes/{quote_uuid}/requirements) — every destination.*
path in that schema is a valid payload key.
Two rules to be aware of:
- Keys must be the literal flat strings shown below. A nested object
({"destination": {"payout_instrument": {...}}}) is not accepted. - Keys that do not start with
destination.are stored but ignored when the recipient is
applied to a transfer.
Example payload for a wire payout:
{
"destination.beneficiary_info.beneficiary_name": "John Smith",
"destination.beneficiary_info.beneficiary_address.street": "1 Market St",
"destination.beneficiary_info.beneficiary_address.city": "San Francisco",
"destination.beneficiary_info.beneficiary_address.country": "US",
"destination.payout_instrument.account_holder_name": "John Smith",
"destination.payout_instrument.bank_name": "HSBC Bank USA",
"destination.payout_instrument.account_number": "1234567890",
"destination.payout_instrument.swift_code": "HSBCUSHH",
"destination.transfer_purpose": "SALARY",
"destination.is_self_transfer": false
}The stored recipient is then applied to a transfer by passing its uuid as recipient_id on
transfer creation; explicit destination.* fields in the transfer request override the
recipient's values.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||