Accounts and Sub-accounts

The three things you work with

Thing	What it is
Main account	Your company's Avenia account. It has its own KYB, balance, limits and beneficiaries.
Sub-account	An account you create under the main account, usually one per end customer. Each sub-account has its own KYC/KYB, balance, limits, beneficiaries and statement. Only the main account creates sub-accounts — see Subaccount Management.
Access	A login on the main account (email, password, MFA) with a set of permissions. API keys belong to an access, and an access can be kept away from specific sub-accounts — see Accesses Management.

Acting for a sub-account

Send subAccountId as a query parameter on the request. It works on quotes, tickets, balances, limits, statements, beneficiaries, KYC and webhook event lists. The async reports (POST /v2/account/reports/...) also accept it in the body — send it in one place only; sending it in both returns 400.

GET  /v2/account/quote/fixed-rate?...&subAccountId=SUB_ACCOUNT_ID
POST /v2/account/tickets/?subAccountId=SUB_ACCOUNT_ID
GET  /v2/account/tickets/{ticketId}?subAccountId=SUB_ACCOUNT_ID
GET  /v2/account/balances?subAccountId=SUB_ACCOUNT_ID

• Without subAccountId, the request acts for the main account. Reading a sub-account's ticket without it returns 404.
• The quote and the ticket must carry the same subAccountId, or the ticket is refused with 400 InvalidFieldError: quoteToken is invalid.

Owner and destination are different fields

• subAccountId decides who owns the operation: whose balance pays, whose limits and KYC apply, and whose statement shows it. The fee settlement default is set on the main account and applies to its sub-accounts.
• ticketBlockchainOutput decides where the output goes: a registered wallet's beneficiaryWalletId, an inline walletAddress, another Avenia account's ID, or the zeroed UUID 00000000-0000-0000-0000-000000000000 for the owner's own balance. beneficiaryWalletId is never a wallet address. See beneficiaryWalletId by operation.

A ticket created with subAccountId=A and a walletAddress belonging to someone else is still sub-account A's operation: A pays, and the tokens go to that address.

Moving funds between your accounts

Use an internal transfer: inputPaymentMethod=INTERNAL, outputPaymentMethod=INTERNAL, the same token on both sides, blockchainSendMethod=PERMIT. Without blockchainSendMethod the quote returns 400 InvalidFieldError: inputCurrency-inputPaymentMethod:blockchainSendMethod is invalid. The full request is in Move Funds Between Your Accounts.

From → To	subAccountId (quote and ticket)	beneficiaryWalletId
Main → sub-account	not sent	the sub-account ID
Sub-account → main	the sub-account ID	the main account ID — the top-level id of GET /v2/account/account-info without subAccountId
Sub-account A → sub-account B	A's ID	B's ID

Paying someone other than the account holder

Pay-ins. Whether a PIX deposit from a payer whose tax ID differs from the account holder's is accepted also depends on your account's configuration. When it isn't, the deposit is refunded to the payer with failureReason third party deposit is not allowed for this user.

PIX payouts to a third party (a beneficiary whose tax ID differs from the account holder's) depend on how your account is configured with Avenia. When they aren't enabled, the ticket is still created, and the payout fails during delivery: the ticket ends PARTIAL-FAILED with third party pay-out rejected and the amount returns to the balance. In that case, pay from a sub-account opened in the beneficiary's own name (with its KYC/KYB done): fund it from the main account with an internal transfer, then pay out from the sub-account. Ask your Avenia contact which setup applies to your account. Both paths, step by step, are in Pay Out by PIX to a Third Party.

inputThirdParty and outputThirdParty don't control any of this. They are required on every quote and reserved for future use; send false. See Third Party Fields.