Skip to main content
POST
Transfer Z$ to a user or a company

Authorizations

X-API-Key
string
header
required

Per-company partner API key (zupy_pk_…). Validated by Zupy against the company integration key hash (Story 14.x); send it on every request as the X-API-Key header. Scoped read-write to the owning company's data.

Body

Body of a transfer: at least one person identifier OR company_id, never both.

amount
string<decimal>
required

Z$ to send, > 0, at most 2 decimals.

Pattern: ^-?\d{0,16}(?:\.\d{0,2})?$
external_reference
string
required

The partner's own id for this transfer. Same reference + same data = the same transfer.

Maximum string length: 200
reason
string

Why you send it; shown in the user's statement (up to 200 characters).

Maximum string length: 200
phone
string | null
Maximum string length: 32
email
string<email> | null
cpf
string | null
Maximum string length: 20
wallet_address
string | null
Maximum string length: 64
name
string | null
Maximum string length: 255
company_id
string | null

Send to a company instead of a person (exclusive with the person identifiers).

Maximum string length: 64

Response

A transfer your partner account made.

id
string<uuid>
required
external_reference
string
required
amount
string<decimal>
required
Pattern: ^-?\d{0,16}(?:\.\d{0,2})?$
reason
string
required
customer_id
string | null
required
destination_company_id
string | null
required

The company you sent to (null for a user).

credited_company_id
string | null
required

The company whose wallet received: the parent, when the destination is a branch.

status
string
required
read-only

settling: the Z$ is already spendable and its on-chain record is pending; settled: recorded on-chain; settlement_failed: the on-chain record failed for good; unknown: contact Zupy support. For a transfer to a company, settlement_failed is not final while Zupy re-sends the last leg: it goes back to settling, then settled.

created_at
string<date-time>
required