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

  1. POST /api/wallet/payout/external/prepare (your backend): send the PIX key, the value and the wallet address. Hodle answers with the price, a payoutIntentId and an unsigned serializedTransaction.
  2. Sign (your app): the user approves the transaction in their wallet. Sign it; do not send it to the network.
  3. POST /api/wallet/payout/external/submit (your backend): send the signed transaction and the payoutIntentId. Hodle answers 202 with a transactionId.
  4. Poll GET /api/wallet/payout/{transactionId} until COMPLETED, FAILED or REFUNDED, or listen for PAYOUT_SUCCESSFUL, PAYOUT_FAILED and PAYOUT_REFUNDED webhooks. 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()
FieldTypeRequiredDescription
networkstringYessolana.
assetstringYesBRS.
valueintegerYesBRL cents the PIX pays. Minimum 500.
pixKeystringYesBeneficiary PIX key.
pixKeyTypestringYesCPF, CNPJ, EMAIL, PHONE or RANDOM.
payerAddressstringYesSolana address of the wallet that holds the BRS and signs.
externalIdstringNoYour idempotency key. The same key never pays twice.
taxIdstringNoBeneficiary CPF/CNPJ, for accounts restricted to paying themselves.
subAccountIdstringNoSub-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

StatusWhen
400Invalid 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.
401Missing or invalid API key.
403Payouts not enabled, account blocked, limit exceeded or destination blocked.
404Submit: intent unknown or expired. Either call: subaccount outside your account.
409Prepare: pricingPending: true; repeat the request. Submit: PAYOUT_IN_PROGRESS; another submit is in flight; retry.
410Submit: PAYOUT_INTENT_EXPIRED; prepare again.
429Prepare: rate limited.
502Prepare: pricing history unavailable; retry.
503PIX payouts temporarily disabled or wallet balance unavailable (BALANCE_UNAVAILABLE); retry.

Some error messages are in Portuguese. Branch on the status and errorCode when present.