Payout Beneficiary
Resolve who owns a PIX key and lock the price of the payout to it, then pay against the quoteId.
Overview
POST /api/wallet/payout/beneficiary returns a PIX key owner's name, masked tax ID and bank, plus a locked price and quoteId for Wallet Payout. API payouts must be enabled on your account; ask support.
No funds are debited. Unlike the indicative Quote, this quote locks the fee, FX rate, asset and destination. For a BR Code, use qrCode on /api/wallet/payout instead.
Flow
POST /api/wallet/payout/beneficiary— show the user the name that came back, and the fee.POST /api/wallet/payoutwithquoteId,walletPinandprotectedSymmetricKey— settles at the quoted price.GET /api/wallet/payout/{transactionId}— poll untilCOMPLETED,FAILEDorREFUNDED.
Use the quote within 5 minutes. It can be consumed by one payout.
Request
curl --request POST \
--url https://api.hodle.com.br/api/wallet/payout/beneficiary \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"value": 5000,
"network": "base",
"asset": "BRLA",
"pixKey": "recipient@example.com",
"pixKeyType": "EMAIL"
}'const res = await fetch('https://api.hodle.com.br/api/wallet/payout/beneficiary', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
value: 5000,
network: 'base',
asset: 'BRLA',
pixKey: 'recipient@example.com',
pixKeyType: 'EMAIL',
}),
})
const quote = await res.json()import os, requests
res = requests.post(
"https://api.hodle.com.br/api/wallet/payout/beneficiary",
headers={
"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
"Content-Type": "application/json",
},
json={
"value": 5000,
"network": "base",
"asset": "BRLA",
"pixKey": "recipient@example.com",
"pixKeyType": "EMAIL",
},
)
quote = res.json()Parameters
| Field | Type | Required | Description |
|---|---|---|---|
value | integer | Yes | Amount the beneficiary receives, in BRL cents. Min 10. The fee is charged on top of it. |
network | string | Yes | polygon, base, tron or solana. |
asset | string | No | Asset to debit: Polygon USDT (default), USDC, BRLA; Base USDC (default), BRLA, BRS; Tron USDT; Solana USDT (default), USDC, BRS. The quoted asset is fixed. |
pixKey | string | Yes | PIX key of the beneficiary. |
pixKeyType | string | Yes | PHONE, CPF, EMAIL, RANDOM or CNPJ. |
taxId | string | No | Beneficiary CPF/CNPJ. Needed when paying a third party — see Third-party operations. |
subAccountId | string | No | Subaccount the payout is for. Use the same one when paying against the quote. |
walletId | string | No | Wallet to quote for. Use the same wallet when paying. |
Response
BRS pricing may return 202 with status: "PENDING" and pricingPending: true. Repeat the request until a quoteId is returned.
{
"success": true,
"status": "PENDING",
"quoteId": "b0f1c7de-9f2b-4a71-9c1e-2f4e2a1d6c88",
"expiresAt": "2026-08-31T14:35:00.000Z",
"settlement": "OWN_ACCOUNT",
"network": "base",
"asset": "BRLA",
"pixKey": "recipient@example.com",
"pixKeyOwner": {
"name": "Thiago Mota dos Santos",
"taxId": "545.***.***-10",
"bankName": "NU PAGAMENTOS - IP"
},
"quote": {
"inputAmount": 50.75,
"inputCurrency": "BRLA",
"outputAmount": 50,
"outputCurrency": "BRL",
"rate": 1,
"fee": 0.75
},
"payoutId": "6a878236a83b0a4e8cc8c40b",
"correlationId": "b0f1c7de-9f2b-4a71-9c1e-2f4e2a1d6c88"
}| Field | Description |
|---|---|
status | PENDING — reserved, awaiting payment. QUOTED — priced, without a reservation. See Reserved payouts. |
quoteId | Pass as quoteId on /api/wallet/payout. |
expiresAt | When the locked price stops being honoured (5 minutes). |
settlement | Which account settles the PIX: OWN_ACCOUNT (the account opened in your name) or HODLE. |
pixKeyOwner | Payee details. Show the masked taxId to the user; do not use it for matching. |
payoutId | Id of the reserved payout at the settling account. Only when status is PENDING. |
correlationId | Idempotency key of that reserved payout. Only when status is PENDING. |
Reading the quote
| Field | Meaning |
|---|---|
inputAmount | Stablecoin debited from the wallet: value + fee, converted at rate. |
outputAmount | BRL the beneficiary receives — exactly value. |
rate | BRL per unit of inputCurrency. 1 for the BRL-pegged assets (BRLA, BRS). |
fee | Hodle's fee, in BRL. Already includes any affiliate discount your account carries. |
Faster payouts and the refill fee
Applies only to payouts with "asset": "BRS". Payouts in BRLA, USDC or USDT
never carry a refill fee: the debited asset already is the balance the PIX
is paid from, so the debit itself refills the liquidity at no extra cost.
A standard BRS payout moves in sequence. Your stablecoins are debited, the licensed virtual asset service provider (VASP) that settles the payout has to receive and credit that amount, and only then is the PIX sent. Most of the time between your request and a paid PIX is spent waiting for that credit.
Faster payouts skip the wait. Hodle keeps settlement liquidity already credited at the VASP, so the PIX is sent from it as soon as your debit is confirmed. Your debit then replaces what the payout used.
That liquidity is finite. When it runs low, Hodle refills it, and the refill
has a cost: converting the debited BRS into the balance the VASP pays from.
That cost is proportional to the amount, so each payout carries its own share
as quote.refillFeeCents, already included in quote.fee.
refillFeeCentsis quoted with the rest of the price and locked by thequoteId. The payout never settles for a different fee.- It is charged only on BRS payouts from accounts with faster payouts
enabled. With faster payouts off it is
0. Quotes for other assets do not carry the field. - If the liquidity cannot cover a payout, the payout still completes through the standard sequence, at the quoted price. It only takes longer.
{
"success": true,
"status": "QUOTED",
"quoteId": "…",
"network": "base",
"asset": "BRS",
"quote": {
"inputAmount": 1001.25,
"inputCurrency": "BRS",
"outputAmount": 1000,
"outputCurrency": "BRL",
"rate": 1,
"fee": 1.25,
"refillFeeCents": 50
}
}In this example the recipient receives R$ 1,000.00. The payout fee is R$ 1.25, of which R$ 0.50 is the refill share (5 bps of the amount).
| Field | Type | Description |
|---|---|---|
quote.fee | number | Total fee for this payout, in BRL. Includes the refill share. |
quote.refillFeeCents | integer | Share of the fee that refills the faster-payout liquidity, in BRL cents. BRS quotes only. |
Paying against the quote
Send the quoteId with the wallet credentials. pixKey and pixKeyType may be omitted —
they come from the quote:
curl --request POST \
--url https://api.hodle.com.br/api/wallet/payout \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"value": 5000,
"network": "base",
"quoteId": "b0f1c7de-9f2b-4a71-9c1e-2f4e2a1d6c88",
"walletPin": "123456",
"protectedSymmetricKey": "AoofiKHyVRLvdrknnXzo..."
}'The payout uses the quote's fee, FX rate, asset and destination. value, network, asset, pixKey, walletId and subAccountId must agree with the quote. Quoted payouts require walletPin and cannot be combined with qrCode, payoutIntentId or signature.
Reserved payouts (status: PENDING)
PENDING means the payout is reserved and will be released when you pay against the quote. QUOTED means it will be created when paid; use quoteId the same way.
There is no cancellation endpoint for unpaid reservations. Request a quote when the user is ready to pay.
Errors
| Status | When |
|---|---|
400 | Invalid parameters or an unresolvable PIX key. On payout: expired, unknown or used quote (quote again), or fields that differ from the quote (correct the request). |
401 | Missing or invalid API key. |
403 | Account blocked, API payouts not enabled (ask support), over a limit, blocked PIX key, or a third-party payout not enabled. |
429 | Quote limit: 5 quotes. Each accepted payout gives one back, and one returns every hour on its own. Wait Retry-After seconds or make a payout. |
502 | FX rate or account limit temporarily unavailable. No payout or quote was created; retry later. |
503 | PIX payments are temporarily disabled, or the quote could not be stored. |