Overview
Xfin Payouts API (1.0)
Partner-facing API for the Xfin ONRAMP service: customers pay BRL via PIX and receive USDT in their crypto wallet.
Authentication
All partner endpoints require an X-Api-Key header containing the raw API
key issued to your partner account. Keys are compared using constant-time
comparison (timing-safe). Contact your Xfin account manager to obtain a key.
Status lifecycle
Each payout moves through the following states:
PENDING → PROCESSING → COMPLETED
↘ FAILED
| Status | Meaning |
|---|---|
PENDING | Payout created; PIX charge generated and awaiting payment |
PROCESSING | PIX payment received; USDT transfer initiated |
COMPLETED | USDT settled to receiver_wallet; blockchain fields populated |
FAILED | Payout could not be completed |
Settlement fields (settled_amount_usdt, blockchain_tx_id,
block_explorer_url, paid_at, confirmed_at) are populated by the
provider webhook when settlement is confirmed. They are empty/zero (or absent
for timestamps) while the payout is PENDING or PROCESSING.
API wire shape
All response fields use snake_case. The request body for
POST /v1/payouts also uses snake_case (amount_brl, receiver_wallet,
pix_key, pix_key_type). Internal/provider/margin fields are never
included in responses.
Rate limiting
Requests to /v1/payouts are rate-limited to 100 requests per minute per API
key (token-bucket). Exceeding the limit returns 429 Too Many Requests with
a Retry-After: 60 header.
Versioning
This API is versioned as v1 (path prefix /v1/). Breaking changes will be
introduced under a new version prefix (e.g. /v2/) with advance notice.
Support
Contact your Xfin account manager for API keys, integration questions, or production support.
- License: Proprietary
- OpenAPI version: 3.1.0
Authentication
apiKey
Raw API key issued to your partner account. Pass in the X-Api-Key
request header. HTTP header names are case-insensitive, so X-Api-Key
and X-API-Key are equivalent. The 401 error body uses the literal text
"missing X-API-Key header" — this reflects the exact runtime message
and is not a contradiction of the scheme name.
Security scheme type: apiKey
Header parameter name: X-Api-Key