Skip to main content

Pay Out by PIX to a Third Party

A third-party payout is a PIX to someone whose CPF/CNPJ differs from the account holder's: paying a supplier, an end customer or a seller. The recipient's CPF/CNPJ is the owner of the PIX key (or of the bank account or BR Code you pay), and it's compared with the holder of the account that creates the ticket. Whether the main account can do it depends on how your account is configured with Avenia, so this recipe has two paths. Ask your Avenia contact which one applies to you.

Path A: pay from the main account​

When your account allows third-party payouts, it's a regular PIX payout. The access behind your API key needs the payOut permission, and if it has enforceAllowedBeneficiaries on, pay a registered beneficiary instead of an inline PIX key.

Quote

GET /v2/account/quote/fixed-rate?inputCurrency=BRLA&inputPaymentMethod=INTERNAL&inputAmount=5&outputCurrency=BRL&outputPaymentMethod=PIX&blockchainSendMethod=PERMIT&inputThirdParty=false&outputThirdParty=false

Ticket, with the beneficiary's PIX key (or a registered beneficiary or full bank details):

POST /v2/account/tickets/
{
  "quoteToken": "eyJ...",
  "ticketBrlPixOutput": {
    "pixKey": "supplier@example.com",
    "pixMessage": "Invoice 1234"
  }
}
{
  "id": "012e4d72-a5cb-48ed-accb-2200071ebf47",
  "expiration": "2026-10-25T18:51:03.172077281Z"
}

Confirm by reading the ticket or waiting for TICKET-COMPLETE. In sandbox the ticket reached PAID, with the beneficiary's tax ID in brazilianFiatReceiverInfo.taxId.

When your account doesn't allow them​

The ticket is still created; the payout fails during delivery. The ticket ends PARTIAL-FAILED with failureReason ticket failed partially: third party pay-out rejected - tokens returned to user's wallet, and the amount, Out Fee included, goes back to your balance as BRLA. Nothing reaches the beneficiary. Use path B.

Path B: pay from a sub-account in the beneficiary's name​

If the main account can't pay third parties, open a sub-account for the beneficiary, with KYC (person) or KYB (company) in the beneficiary's own name. A PIX from that sub-account to the beneficiary's own key is no longer a third-party payout.

  1. Create the sub-account and complete its KYC/KYB — see Subaccount Management and KYC Level 1 or KYB Level 1.
  2. Fund it from the main account with an internal transfer — see Move Funds Between Your Accounts.
  3. Pay out from the sub-account with the same quote and ticket as path A, adding subAccountId=SUB_ACCOUNT_ID to both:
GET  /v2/account/quote/fixed-rate?inputCurrency=BRLA&inputPaymentMethod=INTERNAL&inputAmount=5&outputCurrency=BRL&outputPaymentMethod=PIX&blockchainSendMethod=PERMIT&inputThirdParty=false&outputThirdParty=false&subAccountId=SUB_ACCOUNT_ID
POST /v2/account/tickets/?subAccountId=SUB_ACCOUNT_ID
{
  "quoteToken": "eyJ...",
  "ticketBrlPixOutput": {
    "pixKey": "BENEFICIARY_PIX_KEY"
  }
}
{
  "id": "a82323c2-f549-406e-a458-96dd8502a2b9",
  "expiration": "2026-10-25T18:59:28.229886963Z"
}

In sandbox this ticket reached PAID. Read it with the same subAccountId: GET /v2/account/tickets/{ticketId}?subAccountId=SUB_ACCOUNT_ID.

The PIX key must belong to the same CPF/CNPJ as the sub-account's KYC/KYB; otherwise it's a third-party payout for that sub-account too.

About inputThirdParty and outputThirdParty​

These quote fields don't enable or block third-party payouts. They are reserved; send false. See Third Party Fields.