Skip to content
Xfin Developers

List payouts

GET
/v1/payouts

Returns the authenticated partner’s payouts, ordered newest first. Results are wrapped in an object with payouts and count keys.

Authorizations

Parameters

Query Parameters

limit
integer
default: 50 >= 1 <= 100 
20

Maximum number of payouts to return. Default 50, maximum 100.

Responses

200

List of payouts (may be empty).

Response wrapper for the list endpoint.

object
payouts
required

Payouts belonging to the authenticated partner, ordered newest first.

Array<object>

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
count
required

Number of payouts in this response (≤ requested limit).

integer
3

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"
}