Create a payout

POST

/v1/payouts

Production

Initiates a BRL→USDT ONRAMP payout. The response includes pix_copy_paste, the EMV “PIX copia e cola” string the payer should use to pay.

Idempotency

Supply an optional Idempotency-Key header (any opaque string, e.g. your internal order ID) to make the call idempotent. On a replay with the same key (same partner), the request body is ignored and the original payout is returned unchanged — no new charge is created. A duplicate sent while the original is still in flight (claimed but not yet recorded) returns 409 Conflict. Keys are scoped per partner and expire after 24 hours.

Authorizations

apiKey

Parameters

Header Parameters

Idempotency-Key

string

order-2026-abc-123

Opaque client-generated key (e.g. your internal order ID). When provided, the API returns the original payout on retry; the request body is ignored on replay. Scoped per partner; 24-hour TTL.

Request Body^required

object

amount_brl

required

Amount in BRL to be charged via PIX. Must be greater than 0 and large enough that the quoted USDT amount (amount_brl / exchange_rate) is at least 0.01 USDT (effective floor of a few BRL cents). BRL is handled to 2 decimal places. Settlement is in USDT on Arbitrum (chain ID 42161).

number format: double

> 0

receiver_wallet

required

The USDT wallet address that will receive the settled amount.

string

0xYourWalletAddress

pix_key

required

The payer’s PIX key. Format depends on pix_key_type:

CPF: 11 digits (e.g. 12345678901)
CNPJ: 14 digits (e.g. 12345678000195)
EMAIL: valid email address (e.g. pagador@email.com)
PHONE: Brazilian phone, 10-11 digits with optional +55 (e.g. 11987654321 or +5511987654321)
RANDOM: UUID-format random key (e.g. 123e4567-e89b-12d3-a456-426614174000)

string

pagador@email.com

pix_key_type

required

Type of the pix_key. Case-insensitive at the API level.

string

Allowed values: CPF CNPJ EMAIL PHONE RANDOM

EMAIL

Example

{
  "amount_brl": 100,
  "receiver_wallet": "0xYourWalletAddress",
  "pix_key": "pagador@email.com",
  "pix_key_type": "EMAIL"
}

Responses

201

Payout created successfully.

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

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

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

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

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "partner_id": "partner-abc",
  "status": "PENDING",
  "amount_brl": 100,
  "min_amount_usdt": 18.37,
  "settled_amount_usdt": 0,
  "pix_key": "pagador@email.com",
  "pix_key_type": "EMAIL",
  "receiver_wallet": "0xYourWalletAddress",
  "pix_copy_paste": "00020101021226930014br.gov.bcb.pix...",
  "blockchain_network": "",
  "blockchain_chain_id": 0,
  "blockchain_tx_id": "",
  "block_explorer_url": "",
  "created_at": "2026-06-14T20:00:00Z",
  "updated_at": "2026-06-14T20:00:00Z"
}

400

Validation error (e.g. amount_brl ≤ 0, missing fields, invalid PIX key format).

object

error

required

Human-readable error message.

string

amount_brl must be > 0

Example

{
  "error": "amount_brl must be > 0"
}

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

409

Idempotency conflict. A request with the same Idempotency-Key is already in flight (claimed but not yet recorded). Retry after a short delay.

object

error

required

Human-readable error message.

string

amount_brl must be > 0

Example

{
  "error": "idempotency conflict"
}

429

Rate limit exceeded (100 rpm per key).

object

error

required

Human-readable error message.

string

amount_brl must be > 0

Example

{
  "error": "rate limit exceeded, retry after 60 seconds"
}

Headers

Retry-After

integer

Number of seconds to wait before retrying.

Create a payout

Idempotency

Authorizations

Parameters

Header Parameters

Request Body required

Example

Responses

201

Example

400

Example

401

Example

409

Example

429

Example

Headers

Request Body^required