Wallet Payout

Pay PIX from a user's USDT, USDC, BRLA or BRS balance on Polygon, Base, Tron or Solana in a single API call.

Select a wallet

Pass walletId (data.id from /api/wallet/create) with that wallet's protectedSymmetricKey and its owner's walletPin. Add subAccountId for a customer wallet. Omit walletId to use default selection. See Wallet Keys.

Overview

Pays a PIX key or BR Code (qrCode) from a wallet's stablecoin balance. API payouts must be enabled on your account; ask support. For BRS in a Solana wallet you control, use Payout from Your Own Wallet.

NetworkAssetsAutomatic order
polygonUSDT, USDC, BRLABRLA → USDT → USDC
baseUSDC, BRLA, BRSBRLA → USDC
tronUSDTUSDT
solanaUSDT, USDC, BRSUSDT → USDC

On Polygon and Base, asset is a preference: BRLA is tried first, then the requested USD stablecoin if BRLA cannot cover the full debit plus fee. An explicit Solana USDT or USDC is used directly. Tron always debits USDT regardless of asset.

Tron and BRS require account enablement (ask support). BRS must be requested explicitly, has a minimum value of 500 (R$ 5.00). See BRS.

BRLA and BRS convert 1:1 to BRL; USDT and USDC use the current BRL rate. Network fees are sponsored.

Use Payout Beneficiary to confirm the payee and lock the price before paying.

Flow

  1. Fetch the selected wallet's key with POST /api/wallet/keys if it is not cached from creation. Cache it per walletId and refresh when it changes.
  2. Call POST /api/wallet/payout to receive a transactionId. Do not resend an accepted payout.
  3. Poll GET /api/wallet/payout/{transactionId} every 5 seconds until COMPLETED, FAILED or REFUNDED.

Payouts typically complete in 30–90 seconds. BRS payouts may remain pending for 15–60 minutes.

POST /api/wallet/payout

Request

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": "polygon",
    "pixKey": "recipient@example.com",
    "pixKeyType": "EMAIL",
    "walletPin": "123456",
    "protectedSymmetricKey": "AoofiKHyVRLvdrknnXzo..."
  }'
const res = await fetch('https://api.hodle.com.br/api/wallet/payout', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    value: 5000,
    network: 'polygon',
    pixKey: 'recipient@example.com',
    pixKeyType: 'EMAIL',
    walletPin: '123456',
    protectedSymmetricKey: 'AoofiKHyVRLvdrknnXzo...',
  }),
})
const data = await res.json()
import os, requests

res = requests.post(
"https://api.hodle.com.br/api/wallet/payout",
headers={
"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}",
"Content-Type": "application/json",
},
json={
"value": 5000,
"network": "polygon",
"pixKey": "recipient@example.com",
"pixKeyType": "EMAIL",
"walletPin": "123456",
"protectedSymmetricKey": "AoofiKHyVRLvdrknnXzo...",
},
)
data = res.json()

Parameters

FieldTypeRequiredDescription
valueintegerYesAmount in BRL cents. Min 10 (R$ 0.10), or 500 for BRS. Your per-transaction account limit applies (default R$ 3,000); ask support to raise it.
networkstringYespolygon, base, tron, or solana.
assetstringNoFunding preference; see the network table and selection rules above.
pixKeystringYes (or qrCode / quoteId)PIX key of the recipient. Mutually exclusive with qrCode.
pixKeyTypestringYes (with pixKey, unless quoted)One of PHONE, CPF, EMAIL, RANDOM, CNPJ.
qrCodestringYes (or pixKey)PIX BR Code copy-paste. Mutually exclusive with pixKey.
walletIdstringNoSource wallet (data.id from /api/wallet/create). Must match the owner, subaccount, network and supplied key. Omit for default selection.
walletPinstringYesThe selected wallet owner's PIN.
protectedSymmetricKeystringYesThe value returned by POST /api/wallet/keys.
externalIdstringNoYour idempotency key. Reuse it on retries to receive the original payout (alreadyProcessed: true). Without it, duplicate detection only covers a short window for the same user, value and destination.
subAccountIdstringNoSubaccount this payout belongs to. Defaults to your main account. See What subAccountId does.
quoteIdstringNoA quote from POST /api/wallet/payout/beneficiary. Locks fee, FX rate, asset and destination. Omit pixKey/pixKeyType; supplied fields must match the quote. Requires walletPin; cannot be combined with qrCode, payoutIntentId or signature.
markupobjectNoYour own spread on top of Hodle's fee, paid to your wallet once the PIX is confirmed. { "bps": 0-1000, "fixedCents": >= 0 }, integers. Requires partner markup enabled on the account. See Partner markup.
taxIdstringNoCPF of the beneficiary receiving the PIX, digits only. Omit when paying the account holder. A value that differs from the subaccount's KYC taxId is a third-party operation and needs that enabled — see Third-party operations.

What subAccountId does

Without walletId, account configuration determines which wallet is debited:

  • If subaccounts hold funds, the payout debits the subaccount's wallet. Use its PIN and protected key.
  • If subaccounts are only used for customer attribution, the payout debits your main wallet. Use your PIN and protected key.

Passing both walletId and subAccountId explicitly selects that customer's wallet in either setup. Use the selected wallet's key and its owner's PIN. Ask support which setup applies to your account.

subAccountId is recorded on the payout but is not returned by GET. Keep your own externalId mapping for reconciliation. The same account setup applies to asset deposits.

Response

202 Accepted
{
  "success": true,
  "transactionId": "65f1a8...",
  "status": "PROCESSING",
  "stableAmount": "9.31",
  "valueInBrl": "50.00",
  "fee": "1.55",
  "network": "polygon",
  "asset": "USDT",
  "jobId": "1"
}

stableAmount is the selected asset's total debit, including the fee. asset identifies what was debited. The payout is still in progress; poll GET for its final status.

Fees

With quoteId, the quoted fee applies. Otherwise, default pricing is R$ 1.50 + 2.5% of value, before affiliate discounts. Accounts can have custom fixed or percentage fees per asset and a minimum fee; ask support.

At default pricing, value: 5000 (R$ 50.00) has a fee of R$ 2.75.

Partner markup

Add your own spread to a payout with markup. It is charged on top of Hodle's fee, never instead of it:

markupCents = round(value × bps / 10000) + fixedCents
fee         = Hodle fee + markupCents

The wallet is debited for value + Hodle fee + markup in one atomic on-chain operation. The markup goes to your own wallet (the API key owner's wallet on the payout's network, never a subaccount's), in the debited asset, only after the PIX is confirmed. If the PIX fails and the payout is refunded, the markup is returned to the debited wallet as well.

  • Send at least one of bps or fixedCents above zero; { "bps": 0, "fixedCents": 0 } is the same as no markup.
  • Supported routes: polygon and base (USDT, USDC, BRLA) and solana (USDT, USDC), signed with walletPin. A markup on tron, on BRS, with quoteId, on the signature-only flow (payoutIntentId/signature, or omitting walletPin) or on a route your account cannot carry it on answers MARKUP_UNSUPPORTED_ROUTE before anything is debited. A markup is never silently dropped.
  • Your account needs a wallet on the payout's network to receive the markup (MARKUP_PARTNER_WALLET_NOT_FOUND otherwise).
  • When Hodle's fee plus the markup reach value, the payout is refused with AMOUNT_BELOW_FEE.

The response then carries fee (Hodle fee + markup), feeBreakdown and the markup's amount in the debited asset; stableAmount stays the debit without the markup:

{
  "stableAmount": "20.40",
  "fee": "3.50",
  "feeBreakdown": { "hodleFeeCents": 200, "partnerMarkupCents": 150 },
  "partnerMarkupStableAmount": "0.30"
}

Errors

StatusWhen
400Invalid parameters, unsupported asset/network, wrong PIN or protected key, PIN locked for 24 hours after three failures, insufficient balance (INSUFFICIENT_BALANCE), Tron not enabled, or an expired, used, unknown or mismatched quote. Invalid markup (MARKUP_INVALID), a markup on a route that cannot carry it (MARKUP_UNSUPPORTED_ROUTE), no wallet of yours on the network to receive it (MARKUP_PARTNER_WALLET_NOT_FOUND), or fee plus markup not below value (AMOUNT_BELOW_FEE).
401Missing or invalid API key.
403API payouts or BRS not enabled, account blocked, third-party payouts not enabled, blocked destination, account limit exceeded (PER_TX_LIMIT_EXCEEDED), or markup sent without partner markup enabled (MARKUP_NOT_ENABLED).
404Wallet, subaccount or payout not found within your account.
409Another payout is in progress (PAYOUT_IN_PROGRESS), retry with the same externalId; or this wallet's earlier payouts did not land on-chain within the wait (WALLET_BUSY), retry a few seconds later.
429Rate limited; wait for the interval in the response.
502The FX rate could not be fetched.
503PIX payments are temporarily disabled, or partner markup settlement is temporarily unavailable (MARKUP_SETTLEMENT_UNAVAILABLE).
400
{ "success": false, "error": "Invalid PIN" }
400
{
  "success": false,
  "error": "Insufficient balance for the payout",
  "errorCode": "INSUFFICIENT_BALANCE"
}
409 — this wallet's earlier payouts did not land in time
{
  "success": false,
  "error": "Another payout from this wallet has not landed on-chain yet; retry once it confirms",
  "errorCode": "WALLET_BUSY",
  "retryable": true,
  "blockingTransactionId": "6ad6a83af67d01515bbba20e"
}

Each payout from a wallet signs that wallet's next on-chain nonce, so payouts of one wallet and network are signed one at a time, in arrival order: a request sent while an earlier payout of the same wallet is still landing waits for it (usually a few seconds) and is then accepted. It is refused with WALLET_BUSY only when that wait passes 25 seconds, or when an earlier payout's on-chain status is still being confirmed. Nothing was created or debited. Retry a few seconds later, or poll blockingTransactionId until it has a txHash. For high volume, spread payouts across wallets.

GET /api/wallet/payout/{transactionId}

Poll for the final state.

Request

curl --request GET \
  --url "https://api.hodle.com.br/api/wallet/payout/65f1a8..." \
  --header "Authorization: Bearer $API_KEY"
const res = await fetch(
  `https://api.hodle.com.br/api/wallet/payout/${transactionId}`,
  { headers: { Authorization: `Bearer ${process.env.HODLE_API_KEY}` } },
)
const data = await res.json()
import os, requests

res = requests.get(
f"https://api.hodle.com.br/api/wallet/payout/{transaction_id}",
headers={"Authorization": f"Bearer {os.environ['HODLE_API_KEY']}"},
)
data = res.json()

Response

status: PENDING
{
  "success": true,
  "data": {
    "transactionId": "65f1a8...",
    "status": "PENDING",
    "network": "polygon",
    "txHash": null,
    "endToEndId": null,
    "valueInBrl": "50.00",
    "fee": "1.55",
    "pixKey": "recipient@example.com",
    "qrCode": null,
    "receipt": null,
    "creditParty": null,
    "receiptUrl": null,
    "receiptComplete": null,
    "failureCode": null,
    "failureReason": null,
    "createdAt": "2026-04-28T23:32:10.000Z",
    "updatedAt": "2026-04-28T23:32:10.000Z"
  }
}
status: COMPLETED
{
  "success": true,
  "data": {
    "transactionId": "65f1a8...",
    "status": "COMPLETED",
    "network": "polygon",
    "txHash": "0xeafe9c4985963a7a7d6e49f763cca5c6006693031402d46c0da2fced4519fe03",
    "endToEndId": "E12345678202604281432abcdef123456",
    "valueInBrl": "50.00",
    "fee": "1.55",
    "failureCode": null,
    "failureReason": null,
    "receipt": {
      "endToEndId": "E12345678202604281432abcdef123456",
      "paidAt": "2026-04-28T23:33:41.708Z",
      "amountInBrl": "50.00",
      "payerIspb": "12345678",
      "brCode": null,
      "receiver": {
        "name": "MARIA SOUZA",
        "taxId": "***.241.413-**",
        "pixKey": "recipient@example.com",
        "pixKeyType": "EMAIL",
        "bankName": "Example Bank",
        "bankCode": "001",
        "ispb": "54811417",
        "branch": "0001",
        "account": "****5716",
        "accountType": "TRAN"
      }
    },
    "creditParty": {
      "name": "MARIA SOUZA",
      "taxId": "***.241.413-**",
      "pixKey": "recipient@example.com",
      "pixKeyType": "EMAIL",
      "bankName": "Example Bank",
      "bankCode": "001",
      "ispb": "54811417",
      "branch": "0001",
      "account": "****5716",
      "accountType": "TRAN"
    },
    "receiptUrl": "https://receipts.hodle.com.br/receipts/65f1a8b2c3d4e5f6a7b8c9d0.pdf",
    "receiptComplete": true,
    "createdAt": "2026-04-28T23:32:10.000Z",
    "updatedAt": "2026-04-28T23:33:42.000Z"
  }
}

receipt follows the webhook receipt format. Details may arrive after the payout completes. Missing values are null; older receipts may omit optional fields. Tax IDs and accounts are masked, and bank identifiers are strings that preserve leading zeros.

FieldTypeMeaning
receiptobject | nullLatest available receipt. Its fields are listed in Receipt detail.
creditPartyobject | nullMasked recipient details from receipt.receiver; null until available.
receiptUrlstring | nullPDF download URL. An incomplete PDF can be replaced with more details at the same URL.
receiptCompleteboolean | nulltrue when required details are present, false if incomplete, null if not processed. Independent of payout status.

A payout can be COMPLETED while its receipt is incomplete. Refresh GET for updated details; receiptComplete: false may persist. Completeness requires the end-to-end ID, recipient name and tax ID, bank name and ISPB, branch, account and account type. Bank code, PIX key type and BR Code may still be null.

For QR payouts, receipt.brCode and the PDF include the original BR Code when available; qrCode is the code stored on the transaction.

status: REFUNDED
{
  "success": true,
  "data": {
    "transactionId": "65f1a8...",
    "status": "REFUNDED",
    "txHash": "0xeafe9c...",
    "failureCode": "PAYOUT_FAILED",
    "failureReason": "QR Code inválido"
  }
}

failureReason gives an actionable reason when available, otherwise a generic failure message.

Status values

StatusMeaning
PENDINGPayout in progress. Keep polling.
COMPLETEDPIX confirmed. Final.
FAILEDThe PIX did not complete. Final. See failureCode and failureReason.
REFUNDEDThe PIX did not complete and the debited value was returned to the wallet. Final. failureCode and failureReason say why.

Funding requirements

The wallet must hold enough of one eligible asset to cover value + fee. Balances are checked per asset; there is no automatic swap or split across assets. If the debit succeeds but the PIX fails, the refund uses the same asset and network.

Fund the wallet by sending a supported asset directly to its network address. It becomes spendable when wallet/get reflects the balance; use sync: true for a fresh read.