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.
| Network | Assets | Automatic order |
|---|---|---|
polygon | USDT, USDC, BRLA | BRLA → USDT → USDC |
base | USDC, BRLA, BRS | BRLA → USDC |
tron | USDT | USDT |
solana | USDT, USDC, BRS | USDT → 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
- Fetch the selected wallet's key with
POST /api/wallet/keysif it is not cached from creation. Cache it perwalletIdand refresh when it changes. - Call
POST /api/wallet/payoutto receive atransactionId. Do not resend an accepted payout. - Poll
GET /api/wallet/payout/{transactionId}every 5 seconds untilCOMPLETED,FAILEDorREFUNDED.
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
| Field | Type | Required | Description |
|---|---|---|---|
value | integer | Yes | Amount 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. |
network | string | Yes | polygon, base, tron, or solana. |
asset | string | No | Funding preference; see the network table and selection rules above. |
pixKey | string | Yes (or qrCode / quoteId) | PIX key of the recipient. Mutually exclusive with qrCode. |
pixKeyType | string | Yes (with pixKey, unless quoted) | One of PHONE, CPF, EMAIL, RANDOM, CNPJ. |
qrCode | string | Yes (or pixKey) | PIX BR Code copy-paste. Mutually exclusive with pixKey. |
walletId | string | No | Source wallet (data.id from /api/wallet/create). Must match the owner, subaccount, network and supplied key. Omit for default selection. |
walletPin | string | Yes | The selected wallet owner's PIN. |
protectedSymmetricKey | string | Yes | The value returned by POST /api/wallet/keys. |
externalId | string | No | Your 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. |
subAccountId | string | No | Subaccount this payout belongs to. Defaults to your main account. See What subAccountId does. |
quoteId | string | No | A 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. |
markup | object | No | Your 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. |
taxId | string | No | CPF 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
{
"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 + markupCentsThe 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
bpsorfixedCentsabove zero;{ "bps": 0, "fixedCents": 0 }is the same as no markup. - Supported routes:
polygonandbase(USDT,USDC,BRLA) andsolana(USDT,USDC), signed withwalletPin. A markup ontron, onBRS, withquoteId, on the signature-only flow (payoutIntentId/signature, or omittingwalletPin) or on a route your account cannot carry it on answersMARKUP_UNSUPPORTED_ROUTEbefore 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_FOUNDotherwise). - When Hodle's fee plus the markup reach
value, the payout is refused withAMOUNT_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
| Status | When |
|---|---|
400 | Invalid 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). |
401 | Missing or invalid API key. |
403 | API 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). |
404 | Wallet, subaccount or payout not found within your account. |
409 | Another 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. |
429 | Rate limited; wait for the interval in the response. |
502 | The FX rate could not be fetched. |
503 | PIX payments are temporarily disabled, or partner markup settlement is temporarily unavailable (MARKUP_SETTLEMENT_UNAVAILABLE). |
{ "success": false, "error": "Invalid PIN" }{
"success": false,
"error": "Insufficient balance for the payout",
"errorCode": "INSUFFICIENT_BALANCE"
}{
"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
{
"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"
}
}{
"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.
| Field | Type | Meaning |
|---|---|---|
receipt | object | null | Latest available receipt. Its fields are listed in Receipt detail. |
creditParty | object | null | Masked recipient details from receipt.receiver; null until available. |
receiptUrl | string | null | PDF download URL. An incomplete PDF can be replaced with more details at the same URL. |
receiptComplete | boolean | null | true 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.
{
"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
| Status | Meaning |
|---|---|
PENDING | Payout in progress. Keep polling. |
COMPLETED | PIX confirmed. Final. |
FAILED | The PIX did not complete. Final. See failureCode and failureReason. |
REFUNDED | The 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.