Pay Out - BrCode Guide

You've received your credentials and now you want to start operating Pay Out using Avenia API. Let’s walk through the step-by-step process—from logging in to executing a pay out for your client.

In this simulation, assume you are a mass payment company and your clients wish to pay via brCode.

Once you receive your credentials, use the following endpoint to authenticate and receive your JWT.

info

We highly recommend creating API Keys for security and convenience.

HTTP POST Request

https://api.sandbox.avenia.io:10952/v2/auth/login

Sample JSON Body

{
  "email": "your.email@provider.com",
  "password": "UseAStrongPassword123!"
}

cUrl Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/login" \\
 -H "Content-Type: application/json" \\
 -d '{
     "email": "your.email@provider.com",
     "password": "UseAStrongPassword123!"
 }'

Upon a successful login (HTTP 200), you will receive an email with a token to validate your login.

Using the token (emailToken) sent to your email, call the following endpoint to receive your authentication codes (JWT):

HTTP POST Request

https://api.sandbox.avenia.io:10952/v2/auth/validate-login

Sample JSON Body

{
  "email": "your.email@provider.com",
  "emailToken": "777777"
}

cUrl Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/validate-login" \\
 -H "Content-Type: application/json" \\
 -d '{
     "email": "your.email@provider.com",
     "emailToken": "777777"
 }'

JSON Response

{
  "accessToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "refreshToken": "eyJhbdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Step 1 - Create Subaccount

To register your client, create a subaccount. Subaccounts allow the Main Account (you) to manage your clients.

HTTP POST Request

https://api.sandbox.avenia.io:10952/v2/account/sub-accounts

Field	Type	Description
accountType	string	Specify "INDIVIDUAL" for a personal subaccount.
name	string	A name for the subaccount (e.g., "Jane Doe").

Sample JSON Body

{
  "accountType": "INDIVIDUAL",
  "name": "Jane Doe"
}

cUrl Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/sub-accounts" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
 -H "Content-Type: application/json"
 -d '{
     "accountType": "INDIVIDUAL",
     "name": "Jane Doe"
 }'

JSON Response

The response will include the ID of the created subaccount.

{
  "id": "1ee0a663-922b-4389-9f84-074ccff7085d"
}

Step 2 - KYC for Subaccount

KYC (Know Your Customer) is essential to track who is moving or receiving funds. For subaccounts, perform KYC using the flow below. Be sure to pass the subAccountId parameter.

Since this operation is performed for a subaccount, you must include the field as an endpoint parameter subAccountId.

KYC Level 1 is submitted in three calls: request upload URLs for a selfie and an identity document, upload the files, then submit the personal data with the document IDs. See KYC Level 1 for every field, the Web SDK alternative and the document status endpoints.

1. Request document upload URLs

Call this endpoint twice for the subaccount: once with "documentType": "SELFIE" and once for the identity document (ID, DRIVERS-LICENSE or PASSPORT). Save the id of each response.

https://api.sandbox.avenia.io:10952/v2/documents/?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d

{
  "documentType": "PASSPORT",
  "isDoubleSided": false
}

curl -X POST "https://api.sandbox.avenia.io:10952/v2/documents/?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
 -H "Content-Type: application/json" \
 -d '{ "documentType": "PASSPORT", "isDoubleSided": false }'

{
  "id": "00000000-0000-0000-0000-000000000002",
  "uploadURLFront": "https://<pre-signed-upload-url>"
}

2. Upload the files

Send each file with a PUT to the uploadURLFront (and uploadURLBack, for double-sided documents) returned above. The If-None-Match: * header is required; accepted formats are PNG, JPEG and PDF.

curl -X PUT "https://<pre-signed-upload-url>" \
 -H "Content-Type: image/jpeg" \
 -H "If-None-Match: *" \
 --data-binary "@/path/to/passport.jpg"

3. Submit the KYC Level 1 request

https://api.sandbox.avenia.io:10952/v2/kyc/new-level-1/api?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d

{
  "fullName": "Jane Doe",
  "dateOfBirth": "1990-01-01",
  "countryOfTaxId": "BRA",
  "taxIdNumber": "12345678900",
  "email": "jane.doe@example.com",
  "country": "BRA",
  "state": "SP",
  "city": "SP",
  "zipCode": "00000000",
  "streetAddress": "123 Example Street",
  "uploadedSelfieId": "00000000-0000-0000-0000-000000000001",
  "uploadedDocumentId": "00000000-0000-0000-0000-000000000002"
}

info

Countries follow ISO 3166-1 alpha-3 (e.g. BRA) and states follow ISO 3166-2 subdivision codes (e.g. SP).

curl -X POST "https://api.sandbox.avenia.io:10952/v2/kyc/new-level-1/api?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
 -H "Content-Type: application/json" \
 -d '{
     "fullName": "Jane Doe",
     "dateOfBirth": "1990-01-01",
     "countryOfTaxId": "BRA",
     "taxIdNumber": "12345678900",
     "email": "jane.doe@example.com",
     "country": "BRA",
     "state": "SP",
     "city": "SP",
     "zipCode": "00000000",
     "streetAddress": "123 Example Street",
     "uploadedSelfieId": "00000000-0000-0000-0000-000000000001",
     "uploadedDocumentId": "00000000-0000-0000-0000-000000000002"
 }'

The response returns the ID of the KYC attempt. Use it in the next step to track the validation.

{
  "id": "00000000-0000-0000-0000-000000000003"
}

Step 2.1 - Track KYC Validation

Before proceeding, ensure that the KYC for the subaccount has been successfully validated. Use the following GET endpoint with the attempt id returned by POST /v2/kyc/new-level-1/api:

Since this operation is performed for a subaccount, you must include the field as an endpoint parameter subAccountId.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/kyc/attempts/{kyc-attempt-id}?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/kyc/attempts/{kyc-attempt-id}?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response - COMPLETED example

{
  "attempt": {
    "id": "e51359cd-04b0-4bbc-bf7d-0ee515112d74",
    "levelName": "level-1",
    "submissionData": null,
    "status": "COMPLETED",
    "result": "APPROVED",
    "resultMessage": "",
    "retryable": false,
    "createdAt": "2025-03-25T07:39:40.54713Z",
    "updatedAt": "2025-03-25T07:39:40.54713Z"
  }
}

JSON Response - PENDING example

{
  "attempt": {
    "id": "b83802a1-afe9-46ac-96d6-ade6c5961bd3",
    "levelName": "level-1",
    "submissionData": null,
    "status": "PENDING",
    "result": "",
    "resultMessage": "",
    "retryable": false,
    "createdAt": "2025-03-26T22:50:14.201695Z",
    "updatedAt": "2025-03-26T22:50:14.201695Z"
  }
}

JSON Response - REJECT example

{
  "attempt": {
    "id": "5bafd6cd-ec40-4dd3-83e0-a5af117c304a",
    "levelName": "level-1",
    "submissionData": null,
    "status": "COMPLETED",
    "result": "REJECTED",
    "resultMessage": "name does not match",
    "retryable": false,
    "createdAt": "2025-03-26T22:50:14.201695Z",
    "updatedAt": "2025-03-26T22:50:14.201695Z"
  }
}

Step 3 - Send Funds to Subaccount (Quote)

Thus, to enable the client of this mass payment company (simulated scenario) to make a PIX payment, we must send funds to that client (i.e., the subaccount we created and completed KYC for). To initiate this process, we need to generate a Quote, which represents the exact amount to be transferred to the subaccount. In this example, we will send R$150.00.

Note: Since the funds are being transferred from the main account to the subaccount, it is not necessary to include the subaccount ID as a parameter in this request; including it would cause the quote to be applied to the subaccount itself.

warning

The quote is only valid for 15 seconds!

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate

Field	Value	Description	Required
inputCurrency	BRLA	The currency in which the Main Account will pay (in this case, Brazilian Reais).	yes
inputPaymentMethod	INTERNAL	The payment method (using the Main Account balance).	yes
outputAmount	150	The amount that the subaccount will receive (e.g., 98.58 = R$98.58).	yes
outputCurrency	BRLA	The currency in which the subaccount will receive funds.	yes
outputPaymentMethod	INTERNAL	The method by which the subaccount will receive funds (as an internal balance).	yes
inputThirdParty	false	Reserved field — send `false`. See Third Party Fields.	yes
outputThirdParty	false	Reserved field — send `false`. It does not restrict the destination. See Third Party Fields.	yes
blockchainSendMethod	PERMIT	Since this is a balance transfer, the method is PERMIT.	yes

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRLA&inputPaymentMethod=INTERNAL&outputCurrency=BRL&outputPaymentMethod=PIX-BRCODE&inputThirdParty=false&outputThirdParty=false&blockchainSendMethod=PERMIT" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.quoteToken....",
  "inputCurrency": "BRLA",
  "inputPaymentMethod": "INTERNAL",
  "inputAmount": "150",
  "outputCurrency": "BRLA",
  "outputPaymentMethod": "INTERNAL",
  "outputAmount": "150",
  "markupAmount": "0",
  "markupCurrency": "",
  "blockchainSendMethod": "PERMIT",
  "inputThirdParty": false,
  "outputThirdParty": false,
  "appliedFees": [
    {
      "type": "Markup Fee",
      "description": "Total markup fees represented in the input currency.",
      "amount": "0",
      "currency": "BRLA"
    },
    {
      "type": "In Fee",
      "description": "Fees due to input currency and input payment method.",
      "amount": "0",
      "currency": "BRLA"
    },
    {
      "type": "Conversion Fee",
      "description": "Fees due to conversion from input currency to output currency.",
      "amount": "0",
      "currency": "BRLA"
    },
    {
      "type": "Out Fee",
      "description": "Fees due to output currency and output payment method.",
      "amount": "0",
      "currency": "BRLA"
    },
    {
      "type": "Gas Fee",
      "description": "Fees due to blockchain transaction costs.",
      "amount": "0",
      "currency": "BRLA"
    }
  ],
  "basePrice": "1",
  "pairName": "BRLABRLA"
}

Ticket - Closing the Order

With the quote in hand, we will initiate the order closing process—referred to as "Ticket"—where the quote is finalized and the requested operation is executed, which in our case is a transfer to our subaccount.

Field	Value	Description	Required
quoteToken	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.quoteToken....	The quoteToken obtained from the get quote endpoint.	yes
ticketBlockchainOutput	beneficiaryWalletId	Contains details regarding the ticket blockchain output.	yes
└ beneficiaryWalletId	1ee0a663-922b-4389-9f84-074ccff7085d	The ID of the beneficiary wallet that will receive the funds (i.e. the subaccount ID).	yes

HTTP POST Request

https://api.sandbox.avenia.io:10952/v2/account/tickets

Sample JSON Body

Remember that as beneficiaryWalletId we only need to pass the ID of our sub-account

{
  "quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.quoteToken...."
  "ticketBlockchainOutput": {
    "beneficiaryWalletId": "1ee0a663-922b-4389-9f84-074ccff7085d"
  }
}

cUrl Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/tickets" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
 -H "Content-Type: application/json" \
 -d '{
     "quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.quoteToken....",
     "ticketBlockchainOutput": {
     "beneficiaryWalletId": "1ee0a663-922b-4389-9f84-074ccff7085d"
  }
 }

JSON Response

{
  "id": "a14d6b53-e573-4e68-b34a-2a1b717eb448"
}

Verify status from Ticket

Next, verify if the ticket status is PAID by checking the tickets by id endpoint.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/tickets/YOUR-TICKET-UUID-HERE

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/tickets/a14d6b53-e573-4e68-b34a-2a1b717eb448" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

Here we can see that our filed status was PAID, so our sub-account has R$:150.00 in BRLA

info

Note: The status can be in: UNPAID PROCESSING PAID FAILED PARTIAL-FAILED

{
  "ticket": {
    "id": "a14d6b53-e573-4e68-b34a-2a1b717eb448",
    "externalId": "",
    "workspaceId": "22222222-2222-2222-2222-222222222222",
    "userId": "11111111-1111-1111-1111-111111111111",
    "status": "PAID",
    "reason": "",
    "failureReason": "",
    "createdAt": "2025-04-04T14:51:29.702406Z",
    "updatedAt": "2025-04-04T14:51:50.888868Z",
    "expiresAt": "2025-04-05T14:51:29.701368Z",
    "quote": {
      "id": "61ee7d2f-f658-4c6a-9f4c-b3d510d09b57",
      "ticketId": "385e871a-5628-4aa2-a28d-cafe7c876898",
      "inputCurrency": "BRLA",
      "inputPaymentMethod": "INTERNAL",
      "inputAmount": "150",
      "outputCurrency": "BRLA",
      "outputPaymentMethod": "INTERNAL",
      "outputAmount": "150",
      "markupCurrency": "",
      "markupAmount": "0",
      "sendMethod": "",
      "inputThirdParty": false,
      "outputThirdParty": false,
      "basePrice": "1",
      "appliedFees": [
        {
          "type": "Markup Fee",
          "amount": "0",
          "currency": "BRL",
          "rebatable": false,
          "description": "Total markup fees represented in the input currency."
        },
        {
          "type": "In Fee",
          "amount": "0.2",
          "currency": "BRL",
          "rebatable": true,
          "description": "Fees due to input currency and input payment method."
        },
        {
          "type": "Conversion Fee",
          "amount": "0",
          "currency": "BRL",
          "rebatable": true,
          "description": "Fees due to conversion from input currency to output currency."
        },
        {
          "type": "Out Fee",
          "amount": "0",
          "currency": "BRL",
          "rebatable": true,
          "description": "Fees due to output currency and output payment method."
        },
        {
          "type": "Gas Fee",
          "amount": "0",
          "currency": "BRL",
          "rebatable": false,
          "description": "Fees due to blockchain transaction costs."
        }
      ],
      "pairName": "BRLA",
      "outputBrCode": "",
      "createdAt": "2025-04-04T14:51:29Z"
    },
    "rebate": {
      "id": "94fe28a7-ce0c-4ce3-938f-6a4c0a4eec59",
      "ticketId": "385e871a-5628-4aa2-a28d-cafe7c876898",
      "amount": "0.1",
      "currency": "BRLA",
      "destinationWalletAddress": "0x0000000000000000000000000000000000000001"
    },
    "brazilianFiatSenderInfo": {
      "id": "1203f73b-0be3-45b8-8bbe-46b096a76415",
      "ticketId": "385e871a-5628-4aa2-a28d-cafe7c876898",
      "name": "Example Company Ltda",
      "taxId": "00000000000100",
      "bankCode": "00000000",
      "branchCode": "0001",
      "accountNumber": "0000000000000000",
      "accountType": "payment",
      "endToEndId": "e00000000202504041451XXXXXXXXXXX"
    },
    "blockchainReceiverInfo": {
      "id": "967ac673-a068-4314-a410-86cf1c522c4c",
      "ticketId": "385e871a-5628-4aa2-a28d-cafe7c876898",
      "walletAddress": "0x0000000000000000000000000000000000000002",
      "walletChain": "INTERNAL",
      "walletMemo": "",
      "txHash": "0x0000000000000000000000000000000000000000000000000000000000000001"
    },
    "brlPixInputInfo": {
      "id": "79228b3b-9ec5-4d9f-94a4-9235d18ff291",
      "ticketId": "385e871a-5628-4aa2-a28d-cafe7c876898",
      "referenceLabel": "82H1CRkm16ZsDs45Q76WUdlfQ",
      "additionalData": "Avenia Ticket Payment",
      "brCode": "00020126810014br.gov.bcb.pix01365c2c61a1-134b-4c34-958f-ea3122ac717f0219Avenia Ticket Payment5204000053039865406100.005802BR5917Avenia API Ltda6009Sao Paulo6229052582H1CRkm16ZsDs45Q76WUdlfQ6304D750"
    }
  }
}

Step 4 - Pay Out the brCode

Now that the subaccount is funded with BRLA Token (1:1 with Brazilian Real), proceed to pay the brCode.

Verification of brCode information

First, verify the details behind the brCode using the endpoint below.

Let's look at the scenario where we want to have the data behind the brCode, where we will receive the data: name, taxId (which in Brazil is CPF or CNPJ), bank name, ISPB and the value of that brCode.

Field	Type	Description
pixKey	string	The brCode that needs to be paid (URL-encoded)
decodePixKey	bool	Pass `true` to look up the payee (`name`, `taxId`, `bankName`, `ispb`). Without it, only the data encoded in the brCode itself (`amount`, `expiration`) is returned
subAccountId	string	Optional. The sub-account making the lookup. DICT lookups are rate-limited per user; see DICT Lookup Limits

warning

With decodePixKey=true, each lookup counts against your account's DICT rate limit. When the limit is reached, the endpoint returns HTTP 429.

HTTP GET Request


https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/pix-info

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/pix-info?pixKey=00020101021226580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5920Example%20Company%20Ltda6009SAO%20PAULO62070503***6304ABCD&decodePixKey=true" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "name": "Example Company Ltda",
  "taxId": "00.000.000/0001-00",
  "bankName": "EXAMPLE BANK S.A.",
  "ispb": "00000000",
  "amount": "98.58",
  "expiration": "2025-03-26T21:35:08.75Z"
}

With all steps complete, your subaccount is now ready to execute the payment of the brCode.

Quote

Generate a quote to determine the exact amount to be transferred. Note that the quote is valid for only 15 seconds.

info

Since the subaccount will be the one doing the ticketing (closing the order), it must be passed on to all the endpoints in this section!

warning

The quote is only valid for 15 seconds!

info

Note: We have omitted the quoteToken for better readability, remembering that it is a JWT.

info

Notice that the outputAmount reflects the brCode value, while the inputAmount includes fees.

The fee values may vary depending on the operation.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d

Field	Value	Description
subAccountId	1ee0a663-922b-4389-9f84-074ccff7085d	ID of the subaccount paying the brCode.
inputCurrency	BRLA	Currency used by the subaccount for payment (Brazilian Reais).
inputPaymentMethod	INTERNAL	Payment method (subaccount’s internal balance).
outputCurrency	BRL	Currency in which the brCode will be paid (BRL only).
outputPaymentMethod	PIX-BRCODE	Payment method for the payout (via PIX brCode).
inputThirdParty	false	Reserved field — send `false`. See Third Party Fields.
outputThirdParty	false	Reserved field — send `false`. It does not restrict the destination. See Third Party Fields.
blockchainSendMethod	PERMIT	Specifies that the transfer is automatically handled by Avenia API.
outputBrCode	`00020101021226580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5920Example Company Ltda6009SAO PAULO62070503***6304ABCD`	The brCode that the user will pay.

warning

Some BrCodes do not have a specified value. In such cases, provide either the inputAmount or the outputAmount—only one amount is allowed, so do not include both.

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d&inputCurrency=BRLA&inputPaymentMethod=INTERNAL&outputCurrency=BRL&outputPaymentMethod=PIX-BRCODE&inputThirdParty=false&outputThirdParty=false&blockchainSendMethod=PERMIT&outputBrCode=00020101021226580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5920Example%20Company%20Ltda6009SAO%20PAULO62070503***6304ABCD" \\
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.quoteToken....",
  "inputCurrency": "BRLA",
  "inputPaymentMethod": "INTERNAL",
  "inputAmount": "99.58",
  "outputCurrency": "BRL",
  "outputPaymentMethod": "PIX-BRCODE",
  "outputAmount": "98.58",
  "markupAmount": "0",
  "markupCurrency": "",
  "blockchainSendMethod": "PERMIT",
  "inputThirdParty": false,
  "outputThirdParty": false,
  "appliedFees": [
    {
      "type": "Markup Fee",
      "description": "Total markup fees represented in the input currency.",
      "amount": "0",
      "currency": "BRLA"
    },
    {
      "type": "In Fee",
      "description": "Fees due to input currency and input payment method.",
      "amount": "0",
      "currency": "BRLA"
    },
    {
      "type": "Conversion Fee",
      "description": "Fees due to conversion from input currency to output currency.",
      "amount": "0",
      "currency": "BRLA"
    },
    {
      "type": "Out Fee",
      "description": "Fees due to output currency and output payment method.",
      "amount": "1",
      "currency": "BRLA"
    },
    {
      "type": "Gas Fee",
      "description": "Fees due to blockchain transaction costs.",
      "amount": "0",
      "currency": "BRLA"
    }
  ],
  "basePrice": "1",
  "pairName": "BRLABRL"
}

Ticket - Closing the Order

With the quote in hand, initiate the ticket operation to finalize the order. The subaccount will use the quote to execute the payment.

HTTP POST Request

https://api.sandbox.avenia.io:10952/v2/account/tickets?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d

Sample JSON Body

{
  "quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.quoteToken...."
}

cUrl Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/tickets?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d" \\
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \\
 -H "Content-Type: application/json" \\
 -d '{
 "quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.quoteToken...."
 }'

JSON Response

{
  "id": "a14d6b53-e573-4e68-b34a-2a1b717eb448"
}

Verify status from Ticket

To verify the ticket status, use the following GET endpoint:

info

Note: The status can be in: UNPAID PROCESSING PAID FAILED PARTIAL-FAILED

For a PIX payout, PAID means the PIX was settled at the beneficiary's institution. See PIX payout outcomes for what PARTIAL-FAILED and FAILED mean.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/tickets/a14d6b53-e573-4e68-b34a-2a1b717eb448?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/tickets/a14d6b53-e573-4e68-b34a-2a1b717eb448?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "ticket": {
    "id": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
    "externalId": "",
    "workspaceId": "22222222-2222-2222-2222-222222222222",
    "userId": "11111111-1111-1111-1111-111111111111",
    "status": "PAID",
    "reason": "",
    "failureReason": "",
    "createdAt": "2025-04-04T16:30:45.878456Z",
    "updatedAt": "2025-04-04T16:31:25.355513Z",
    "expiresAt": "2025-04-05T16:30:45.878141Z",
    "quote": {
      "id": "0bc38087-f646-4b23-9dda-350204163edf",
      "ticketId": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
      "inputCurrency": "BRLA",
      "inputPaymentMethod": "INTERNAL",
      "inputAmount": "99.58",
      "outputCurrency": "BRL",
      "outputPaymentMethod": "PIX-BRCODE",
      "outputAmount": "98.58",
      "markupCurrency": "",
      "markupAmount": "0",
      "sendMethod": "PERMIT",
      "inputThirdParty": false,
      "outputThirdParty": false,
      "basePrice": "1",
      "appliedFees": [
        {
          "type": "Markup Fee",
          "amount": "0",
          "currency": "BRLA",
          "rebatable": false,
          "description": "Total markup fees represented in the input currency."
        },
        {
          "type": "In Fee",
          "amount": "0",
          "currency": "BRLA",
          "rebatable": true,
          "description": "Fees due to input currency and input payment method."
        },
        {
          "type": "Conversion Fee",
          "amount": "0",
          "currency": "BRLA",
          "rebatable": true,
          "description": "Fees due to conversion from input currency to output currency."
        },
        {
          "type": "Out Fee",
          "amount": "1",
          "currency": "BRLA",
          "rebatable": true,
          "description": "Fees due to output currency and output payment method."
        },
        {
          "type": "Gas Fee",
          "amount": "0",
          "currency": "BRLA",
          "rebatable": false,
          "description": "Fees due to blockchain transaction costs."
        }
      ],
      "pairName": "BRLABRL",
      "outputBrCode": "00020126740014br.gov.bcb.pix0136d5f144f6-a81c-4dc4-a922-0d8a999a580c0212Avenia Deposit5204000053039865802BR5917Avenia API Ltda6009Sao Paulo62100506000003630474CD",
      "createdAt": "2025-04-04T16:30:45Z"
    },
    "rebate": {
      "id": "b8e88eab-77b7-49e1-89b0-f05dd4b5562b",
      "ticketId": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
      "amount": "0.5",
      "currency": "BRLA",
      "destinationWalletAddress": "0x0000000000000000000000000000000000000001"
    },
    "brazilianFiatReceiverInfo": {
      "id": "5f604282-fd2b-4280-9d53-0ceac5d6aada",
      "ticketId": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
      "taxId": "00.000.000/0001-00",
      "userName": "Example Company Ltda",
      "bankCode": "00020126740014br.gov.bcb.pix0136d5f144f6-a81c-4dc4-a922-0d8a999a580c0212Avenia Deposit5204000053039865802BR5917Avenia API Ltda6009Sao Paulo62100506000003630474CD",
      "brCode": "00020126740014br.gov.bcb.pix0136d5f144f6-a81c-4dc4-a922-0d8a999a580c0212Avenia Deposit5204000053039865802BR5917Avenia API Ltda6009Sao Paulo62100506000003630474CD",
      "endToEndId": "e00000000202504041630XXXXXXXXXXX"
    },
    "blockchainSenderInfo": {
      "id": "3186fe63-3c07-4d76-b3d5-6ab3af3117d2",
      "ticketId": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
      "walletAddress": "0x0000000000000000000000000000000000000002",
      "txHash": "0x0000000000000000000000000000000000000000000000000000000000000002"
    },
    "brlPixOutputInfo": {
      "id": "4edace6f-1fb4-4291-8662-cca72c812d18",
      "ticketId": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
      "pixMessage": "",
      "senderAccountBankName": "Example Bank",
      "senderAccountNumber": "0000000000000000"
    },
    "blockchainInputInfo": {
      "id": "e978e7a3-0206-4857-ab57-f770bdcfdb4b",
      "ticketId": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
      "r": "",
      "s": "",
      "v": 0,
      "nonce": 0,
      "deadline": 0,
      "personalSignature": "",
      "personalSignatureDeadline": 0
    }
  }
}

Reversals

Let’s take a closer look at what happens when there’s a response to a sent Pix. It’s also good to remember that to get real-time insight into what’s happening, you should register and activate your webhooks.

When a return of funds is detected, a new ticket will be created. The inputAmount of this new ticket will reflect the amount returned by the customer. Consequently, the outputAmount will be set at the moment the new ticket is generated — and that value will be credited back to your account in Avenia's, specifically to the Avenia Account that generated the refunded ticket.

A Ticket Event webhook will be triggered, just like with any new ticket. Pay attention to the reason field — it will contain a message linking both operations (indicating that it was a refund). For example:

Pay out reversed by customer. Original ticket id: UUID-OF-THE-ORIGINAL-TICKET

The new ticket's externalId is also set to the original ticket's ID, so you can link both operations programmatically. The original payout ticket stays PAID; the reversal is represented only by the new incoming ticket. See PIX payout outcomes for every final state of a PIX payout.

tip

This section covers reversals initiated by the payee's institution. To return a PIX deposit you received, see Refund Deposit Operations.

Conclusion

You have successfully completed the entire Pay Out process using Avenia API. In this guide, you began by logging in and validating your credentials to receive the necessary authentication tokens. You then created a subaccount to register your client and performed the KYC process—ensuring all required identity verifications were completed. Once the subaccount was verified, you proceeded to fund it by generating a quote that detailed the transaction amount, applicable fees, and exchange rates (valid for only 15 seconds). With the quoteToken obtained, you closed the ticket to execute the payment order, and finally, you verified that the ticket status was marked as PAID. This structured and modular approach provides you with a secure and efficient framework to manage mass payment operations for your clients, ensuring transparency, compliance, and smooth transaction execution.

Login​

HTTP POST Request​

Sample JSON Body​

cUrl Example​

Validate Login​

HTTP POST Request​

Sample JSON Body​

cUrl Example​

JSON Response​

Step 1 - Create Subaccount​

HTTP POST Request​

Sample JSON Body​

cUrl Example​

JSON Response​

Step 2 - KYC for Subaccount​

1. Request document upload URLs​

2. Upload the files​

3. Submit the KYC Level 1 request​

Step 2.1 - Track KYC Validation​

HTTP GET Request​

cUrl Example​

JSON Response - COMPLETED example​

JSON Response - PENDING example​

JSON Response - REJECT example​

Step 3 - Send Funds to Subaccount (Quote)​

HTTP GET Request​

cUrl Example​

JSON Response​

Ticket - Closing the Order​

HTTP POST Request​

Sample JSON Body​

cUrl Example​

JSON Response​

Verify status from Ticket​

HTTP GET Request​

cUrl Example​

JSON Response​

Step 4 - Pay Out the brCode​

Verification of brCode information​

HTTP GET Request​

cUrl Example​

JSON Response​

Quote​

HTTP GET Request​

cUrl Example​

JSON Response​

Ticket - Closing the Order​

HTTP POST Request​

Sample JSON Body​

cUrl Example​

JSON Response​

Verify status from Ticket​

HTTP GET Request​

cUrl Example​

JSON Response​

Reversals​

Conclusion​

Login

HTTP POST Request

Sample JSON Body

cUrl Example

Validate Login

HTTP POST Request

Sample JSON Body

cUrl Example

JSON Response

Step 1 - Create Subaccount

HTTP POST Request

Sample JSON Body

cUrl Example

JSON Response

Step 2 - KYC for Subaccount

1. Request document upload URLs

2. Upload the files

3. Submit the KYC Level 1 request

Step 2.1 - Track KYC Validation

HTTP GET Request

cUrl Example

JSON Response - COMPLETED example

JSON Response - PENDING example

JSON Response - REJECT example

Step 3 - Send Funds to Subaccount (Quote)

HTTP GET Request

cUrl Example

JSON Response

Ticket - Closing the Order

HTTP POST Request

Sample JSON Body

cUrl Example

JSON Response

Verify status from Ticket

HTTP GET Request

cUrl Example

JSON Response

Step 4 - Pay Out the brCode

Verification of brCode information

HTTP GET Request

cUrl Example

JSON Response

Quote

HTTP GET Request

cUrl Example

JSON Response

Ticket - Closing the Order

HTTP POST Request

Sample JSON Body

cUrl Example

JSON Response

Verify status from Ticket

HTTP GET Request

cUrl Example

JSON Response

Reversals

Conclusion