Skip to main content

Refunds and Transfers FAQ

Short answers to the questions integrators ask most about PIX payouts, moving funds between accounts, refunds and paying or being paid by third parties. Each answer links to the page with the full detail.

How do I check who owns a PIX key before paying it?​

Call GET /v2/account/bank-accounts/brl/pix-info?pixKey=...&decodePixKey=true. It returns the holder's name, taxId, bankName and ispb, for PIX keys and BR Codes alike. A CPF comes back partially masked. Only the presence of decodePixKey is checked, so decodePixKey=false also runs the lookup.

See Get Pix Info.

Why does the PIX key lookup return 429?​

Lookups with decodePixKey draw from a budget per account that refills over time, and keys that aren't registered cost more than valid ones. Pass the end user's subAccountId so each sub-account uses its own budget. Validate the key format first, don't repeat a key that returned 400, and back off on 429.

See Lookup limits.

Do I send an amount when paying a BR Code?​

Quote with outputPaymentMethod=PIX-BRCODE and the code in outputBrCode. When the BR Code carries an amount, the quote's outputAmount is that amount and inputAmount includes the fees. Don't send inputAmount then; an outputAmount other than the code's amount returns 400. When it has no amount, send exactly one of inputAmount or outputAmount. The ticket then needs only the quoteToken.

See Pay Out - BrCode Guide and Option 4: Using brCode.

Why is my PIX message refused?​

pixMessage accepts only letters, digits and spaces, up to 100 characters; anything else returns 400 InvalidFieldError: ticketBrlPixOutput.pixMessage is invalid. It's optional, so leave it out when you don't need it.

See Crypto to PIX.

How do I know which banks are blocked before paying out?​

GET /v2/account/bank-accounts/brl/blacklisted-ispbs lists the institutions (by ISPB) blocked for your account, and whether each is blocked for pay-ins, payouts or both. Add subAccountId for a sub-account. A payout to a blocked institution ends PARTIAL-FAILED with receiver bank institution is blocked, and the amount returns to your balance.

See Verifying Blocked Institutions.

What is the zero UUID 00000000-0000-0000-0000-000000000000?​

As beneficiaryWalletId on an INTERNAL output, it means "the account running this operation": the sub-account in subAccountId, or the main account when you don't send one. Use it to credit your own Avenia balance.

See beneficiaryWalletId by operation.

Is beneficiaryWalletId a wallet address or an account ID?​

It's always an ID, never a wallet address. For a blockchain output it's the id of a wallet you registered. For an INTERNAL output it's the zero UUID or the ID of another of your accounts. To send to an address you haven't registered, use walletChain and walletAddress instead, unless your access enforces allowed beneficiaries.

See beneficiaryWalletId by operation.

If I send subAccountId and a walletAddress, which one decides where the money goes?​

walletAddress decides where the tokens are delivered. subAccountId decides who owns the operation: whose balance pays, whose limits and KYC apply, and whose statement shows it. A ticket created for sub-account A with someone else's address is still A's operation.

See Owner and destination are different fields.

How do I move funds from a sub-account to the main account?​

Use an internal transfer. Quote INTERNAL to INTERNAL in the same token, with blockchainSendMethod=PERMIT and the sub-account's subAccountId. Then create the ticket with the same subAccountId and the main account ID in beneficiaryWalletId: that's the top-level id of GET /v2/account/account-info called without subAccountId.

See Move Funds Between Your Accounts.

Why does the refund quote have an outputAmount when I don't send an amount?​

A refund always returns the full original deposit, so the quote fills the amounts in. outputAmount is what the payer gets back, and inputAmount is what leaves your balance. With IMMEDIATE fee settlement that's the deposit plus the refund's own fees; with EOM or FEE_ACCOUNT, the deposit alone.

See Refund a PIX Deposit.

Can someone other than the account holder pay a PIX deposit?​

It depends on your account's configuration. When third-party deposits aren't accepted, a PIX from a payer whose tax ID differs from the account holder's is refunded with failureReason third party deposit is not allowed for this user. The payer then has to pay from the holder's own bank account.

See Paying someone other than the account holder.

Can I pay a third party's PIX from the main account without onboarding a sub-account?​

It depends on how your account is configured with Avenia, so ask your Avenia contact. When it isn't enabled, the ticket is created but ends PARTIAL-FAILED with third party pay-out rejected, and the amount goes back to your balance. The alternative is a sub-account in the beneficiary's own name, funded from the main account with an internal transfer.

See Pay Out by PIX to a Third Party.

Should inputThirdParty and outputThirdParty be true or false?​

false, both of them. They're required on every quote but reserved for future use. Don't mark them true to make a third-party payment work: they don't enable or block payments to or from third parties.

See Third Party Fields.