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

  1. POST /api/wallet/payout/beneficiary — show the user the name that came back, and the fee.
  2. POST /api/wallet/payout with quoteId, walletPin and protectedSymmetricKey — settles at the quoted price.
  3. GET /api/wallet/payout/{transactionId} — poll until COMPLETED, FAILED or REFUNDED.

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

FieldTypeRequiredDescription
valueintegerYesAmount the beneficiary receives, in BRL cents. Min 10. The fee is charged on top of it.
networkstringYespolygon, base, tron or solana.
assetstringNoAsset to debit: Polygon USDT (default), USDC, BRLA; Base USDC (default), BRLA, BRS; Tron USDT; Solana USDT (default), USDC, BRS. The quoted asset is fixed.
pixKeystringYesPIX key of the beneficiary.
pixKeyTypestringYesPHONE, CPF, EMAIL, RANDOM or CNPJ.
taxIdstringNoBeneficiary CPF/CNPJ. Needed when paying a third party — see Third-party operations.
subAccountIdstringNoSubaccount the payout is for. Use the same one when paying against the quote.
walletIdstringNoWallet 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.

200 OK
{
  "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"
}
FieldDescription
statusPENDING — reserved, awaiting payment. QUOTED — priced, without a reservation. See Reserved payouts.
quoteIdPass as quoteId on /api/wallet/payout.
expiresAtWhen the locked price stops being honoured (5 minutes).
settlementWhich account settles the PIX: OWN_ACCOUNT (the account opened in your name) or HODLE.
pixKeyOwnerPayee details. Show the masked taxId to the user; do not use it for matching.
payoutIdId of the reserved payout at the settling account. Only when status is PENDING.
correlationIdIdempotency key of that reserved payout. Only when status is PENDING.

Reading the quote

FieldMeaning
inputAmountStablecoin debited from the wallet: value + fee, converted at rate.
outputAmountBRL the beneficiary receives — exactly value.
rateBRL per unit of inputCurrency. 1 for the BRL-pegged assets (BRLA, BRS).
feeHodle'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.

  • refillFeeCents is quoted with the rest of the price and locked by the quoteId. 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).

FieldTypeDescription
quote.feenumberTotal fee for this payout, in BRL. Includes the refill share.
quote.refillFeeCentsintegerShare 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

StatusWhen
400Invalid 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).
401Missing or invalid API key.
403Account blocked, API payouts not enabled (ask support), over a limit, blocked PIX key, or a third-party payout not enabled.
429Quote 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.
502FX rate or account limit temporarily unavailable. No payout or quote was created; retry later.
503PIX payments are temporarily disabled, or the quote could not be stored.