Payout from Your Own Wallet
Pay a PIX from BRS in your own Solana wallet. Your user signs the transfer; Hodle pays the PIX.
This flow requires API payouts and BRS payouts enabled on your account; ask support.
Overview
Use this flow for BRS in a Solana wallet you control. For wallets created with /api/wallet/create, use Wallet Payout with walletPin.
Your user signs a transfer of value + fee BRS to Hodle. Network fees are sponsored; the wallet needs no SOL.
Flow
POST /api/wallet/payout/external/prepare(your backend): send the PIX key, the value and the wallet address. Hodle answers with the price, apayoutIntentIdand an unsignedserializedTransaction.- Sign (your app): the user approves the transaction in their wallet. Sign it; do not send it to the network.
POST /api/wallet/payout/external/submit(your backend): send the signed transaction and thepayoutIntentId. Hodle answers202with atransactionId.- Poll
GET /api/wallet/payout/{transactionId}untilCOMPLETED,FAILEDorREFUNDED, or listen forPAYOUT_SUCCESSFUL,PAYOUT_FAILEDandPAYOUT_REFUNDEDwebhooks. Do not resend an accepted payout.
The intent expires 60 seconds after prepare. If the user takes longer, prepare again.
Your API key stays on your backend. The app only receives serializedTransaction and
returns the signed bytes.
Fee
The fee is 0.00 while the payout spends BRS Hodle delivered to that wallet. BRS that
reached the wallet from somewhere else pays the external-origin fee. feeReason in the
prepare response says which one applied (FEE_WAIVED when the account has no payout
fee), and amount is value + fee: the BRS that
leaves the wallet. The PIX pays value.
Prepare
curl --request POST \
--url https://api.hodle.com.br/api/wallet/payout/external/prepare \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"network": "solana",
"asset": "BRS",
"value": 500,
"pixKey": "recipient@example.com",
"pixKeyType": "EMAIL",
"payerAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
"externalId": "order-1234"
}'const res = await fetch('https://api.hodle.com.br/api/wallet/payout/external/prepare', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.HODLE_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
network: 'solana',
asset: 'BRS',
value: 500,
pixKey: 'recipient@example.com',
pixKeyType: 'EMAIL',
payerAddress: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU',
externalId: 'order-1234',
}),
})
const prepared = await res.json()| Field | Type | Required | Description |
|---|---|---|---|
network | string | Yes | solana. |
asset | string | Yes | BRS. |
value | integer | Yes | BRL cents the PIX pays. Minimum 500. |
pixKey | string | Yes | Beneficiary PIX key. |
pixKeyType | string | Yes | CPF, CNPJ, EMAIL, PHONE or RANDOM. |
payerAddress | string | Yes | Solana address of the wallet that holds the BRS and signs. |
externalId | string | No | Your idempotency key. The same key never pays twice. |
taxId | string | No | Beneficiary CPF/CNPJ, for accounts restricted to paying themselves. |
subAccountId | string | No | Sub-account the payout is attributed to. |
{
"success": true,
"payoutIntentId": "3f6c2a8e-5b1d-4d7e-9a0c-1e2f3a4b5c6d",
"serializedTransaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA...",
"network": "solana",
"asset": "BRS",
"amount": "5.00",
"valueInBrl": "5.00",
"fee": "0.00",
"feeReason": "INTERNAL_COVERED",
"expiresAt": "2026-10-02T14:35:00.000Z"
}Sign
Decode the base64 serializedTransaction, sign it with the wallet at payerAddress, and return the signed bytes to your backend as base64 signedTransaction. Sign without broadcasting; submit the signed transaction to Hodle unchanged.
Submit
curl --request POST \
--url https://api.hodle.com.br/api/wallet/payout/external/submit \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"payoutIntentId": "3f6c2a8e-5b1d-4d7e-9a0c-1e2f3a4b5c6d",
"signedTransaction": "AbcD...base64..."
}'{
"success": true,
"transactionId": "6a878236a83b0a4e8cc8c40b",
"externalId": "order-1234",
"status": "PROCESSING",
"stableAmount": "5.00",
"valueInBrl": "5.00",
"fee": "0.00",
"network": "solana",
"asset": "BRS"
}A rejected submit leaves the intent available for another signature until it expires. If the PIX fails after the BRS left the wallet, the BRS is returned to payerAddress.
Idempotency
Each payoutIntentId becomes at most one payout. Send externalId to make the whole
order idempotent: a prepare for an externalId that already paid answers 200 with
alreadyProcessed: true and that payout's transactionId instead of a new transaction,
so check alreadyProcessed before asking the user to sign:
{
"success": true,
"alreadyProcessed": true,
"transactionId": "6a878236a83b0a4e8cc8c40b",
"status": "PENDING",
"txHash": null
}Repeated submits of the same payoutIntentId return 200, alreadyProcessed: true and the same transactionId. Different wallets paying the same value to the same key are separate payouts unless they share externalId.
Errors
| Status | When |
|---|---|
400 | Invalid fields. Prepare: value below R$ 5.00, invalid payer (INVALID_PAYER, including a Hodle wallet) or INSUFFICIENT_BALANCE. Submit: changed transaction or missing/invalid payer signature; the intent is kept. |
401 | Missing or invalid API key. |
403 | Payouts not enabled, account blocked, limit exceeded or destination blocked. |
404 | Submit: intent unknown or expired. Either call: subaccount outside your account. |
409 | Prepare: pricingPending: true; repeat the request. Submit: PAYOUT_IN_PROGRESS; another submit is in flight; retry. |
410 | Submit: PAYOUT_INTENT_EXPIRED; prepare again. |
429 | Prepare: rate limited. |
502 | Prepare: pricing history unavailable; retry. |
503 | PIX payouts temporarily disabled or wallet balance unavailable (BALANCE_UNAVAILABLE); retry. |
Some error messages are in Portuguese. Branch on the status and errorCode when present.