Skip to content
Xfin Developers

Get payout by ID

GET
/v1/payouts/{id}

Returns a single payout by ID. Returns 404 if the payout does not exist or does not belong to the authenticated partner (partner-scoped).

Authorizations

Parameters

Path Parameters

id
required
string format: uuid 
550e8400-e29b-41d4-a716-446655440000

The payout UUID.

Responses

200

Payout found.

A partner-facing payout record. All fields use snake_case. Internal, provider, and margin fields are excluded from this response.

Quote integrity: min_amount_usdt is the guaranteed minimum USDT the receiver will get. It is computed at creation time by applying a configurable spread buffer to the spot rate: min = amount_brl / (spot_rate × 1.06). The raw spot-based estimate (amount_usdt_quoted) is intentionally excluded because it over-promises (ignores 4Pay’s settlement spread).

Settlement fields (settled_amount_usdt, blockchain_tx_id, block_explorer_url, paid_at, confirmed_at) are populated only after the provider webhook confirms settlement (when status is COMPLETED). paid_at and confirmed_at are omitted entirely (not present in the JSON object) when the payout has not yet been paid or confirmed.

object
id

Unique payout identifier (UUID v4).

string format: uuid 
550e8400-e29b-41d4-a716-446655440000
partner_id

The partner account that owns this payout.

string
partner-abc
status

Current payout status.

  • PENDING: PIX charge created; awaiting payment.
  • PROCESSING: PIX payment received; USDT transfer initiated.
  • COMPLETED: USDT settled to receiver_wallet.
  • FAILED: Payout could not be completed.
string
Allowed values: PENDING PROCESSING COMPLETED FAILED 
PENDING
amount_brl

BRL amount charged via PIX.

number format: double 
100
min_amount_usdt

Minimum USDT the receiver is guaranteed. Computed at creation time from the spot rate with a spread buffer applied: min = amount_brl / (spot_rate × (1 + buffer)) where buffer is 6% by default. The actual settled_amount_usdt after settlement is ≥ this value under normal market conditions; a monitoring alert fires if it ever falls below.

number format: double 
18.37
settled_amount_usdt

Actual USDT amount received by receiver_wallet after provider spread. Should be ≥ min_amount_usdt. Populated after settlement.

number format: double 
19.38
pix_key

The payer’s PIX key.

string
pagador@email.com
pix_key_type

Type of the PIX key.

string
Allowed values: CPF CNPJ EMAIL PHONE RANDOM 
EMAIL
receiver_wallet

The USDT wallet address that received (or will receive) the settled amount.

string
0xYourWalletAddress
pix_copy_paste

EMV “PIX copia e cola” charge string. The payer copies this into their banking app to pay. Present from creation; used only while status == PENDING.

string
00020101021226930014br.gov.bcb.pix...
blockchain_network

Blockchain network name on which the USDT was settled (e.g. "Arbitrum"). Populated after settlement.

string
Arbitrum
blockchain_chain_id

EVM chain ID of the settlement network (e.g. 42161 for Arbitrum). Populated after settlement.

integer
42161
blockchain_tx_id

Blockchain transaction hash for the USDT transfer. Populated after settlement (status == COMPLETED).

string
0xabc123...
block_explorer_url

Full URL to the transaction on a block explorer. Populated after settlement.

string format: uri 
https://arbiscan.io/tx/0xabc123...
paid_at

UTC timestamp when the PIX payment was received by the provider. Omitted (not present) if the payout has not yet been paid.

string format: date-time 
2026-06-14T20:15:00Z
confirmed_at

UTC timestamp when the provider confirmed settlement. Omitted (not present) if the payout has not yet been confirmed.

string format: date-time 
2026-06-14T20:17:30Z
created_at

UTC timestamp when the payout was created.

string format: date-time 
2026-06-14T20:00:00Z
updated_at

UTC timestamp of the last update to this payout record.

string format: date-time 
2026-06-14T20:17:30Z

401

Missing or invalid API key.

object
error
required

Human-readable error message.

string
amount_brl must be > 0
Example
{
  "error": "missing X-API-Key header"
}

404

Payout not found or not owned by this partner.

object
error
required

Human-readable error message.

string
amount_brl must be > 0
Example
{
  "error": "payout not found"
}