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 API endpoint 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.

HTTP POST Request

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

Field	Type	Required	Description
fullName	string	Yes	The complete name of the individual.
dateOfBirth	string	Yes	The date of birth of the individual (Format: YYYY-MM-DD).
countryOfDocument	string	Yes	The country issuing the document.
documentType	string	Yes	The type of document (must be one of ID, Passport, Driver's License).
documentNumber	string	Yes	The number of the document.
countryOfTaxId	string	Yes	The country where the tax identification number was issued.
taxIdNumber	string	Yes	The tax identification number of the individual.
email	string	No	The email address of the individual.
phone	string	No	The phone number of the individual.
country	string	Yes	The country of residence.
state	string	Yes	The state/province of residence.
city	string	Yes	The city of residence.
zipCode	string	Yes	The postal code of the residence.
streetAddress	string	Yes	The street address of the residence.

info

All countries and states follow the ISO Alpha-3 standard (Example: USA-CA)

Sample JSON Body

{
  "fullName": "Jane Doe",
  "dateOfBirth": "1999-08-16",
  "countryOfDocument": "BRA",
  "documentType": "Passport",
  "documentNumber": "UJ252482",
  "countryOfTaxId": "BRA",
  "taxIdNumber": "75764220173",
  "country": "BRA",
  "state": "SP",
  "city": "SP",
  "zipCode": "12243010",
  "streetAddress": "Rua Madre Paula"
}

cUrl Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/kyc/level-1/api?subAccountId=1ee0a663-922b-4389-9f84-074ccff7085d"
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 -H "Content-Type: application/json"
 -d '{
     "fullName": "Jane Doe",
     "dateOfBirth": "1999-08-16",
     "countryOfDocument": "BRA",
     "documentType": "Passport",
     "documentNumber": "UJ252482",
     "countryOfTaxId": "BRA",
     "taxIdNumber": "75764220173",
     "country": "BRA",
     "state": "SP",
     "city": "SP",
     "zipCode": "12243010",
     "streetAddress": "Rua Madre Paula"
 }

JSON Response

{
  "id": "1ee11163-9tjb-4389-9f84-074ccff7085d"
}

Step 2.1 - Track KYC Validation

Before proceeding, ensure that the KYC for the subaccount has been successfully validated. Use the following GET endpoint:

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/**YOUR-KYC-ID-HERE**?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	Since the subaccount’s funds are sourced from the Main Account, this field is not needed.	yes
outputThirdParty	false	For payments to a subaccount, this should remain false (change to true if paying a third party).	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": "2ac803ad-faf7-489f-9c1a-c6a64072e699",
    "userId": "05505dde-c2e4-47c5-bd5c-071b4c4bb6a4",
    "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": "0xb6e8860883039b6db937639b94e9a10ff7971bb6"
    },
    "brazilianFiatSenderInfo": {
      "id": "1203f73b-0be3-45b8-8bbe-46b096a76415",
      "ticketId": "385e871a-5628-4aa2-a28d-cafe7c876898",
      "name": "Ada Capital Gestao de Recursos Ltda",
      "taxId": "45981761000100",
      "bankCode": "20018183",
      "branchCode": "0001",
      "accountNumber": "5703785980624896",
      "accountType": "payment",
      "endToEndId": "e20018183202504041451vbks2pewbiz"
    },
    "blockchainReceiverInfo": {
      "id": "967ac673-a068-4314-a410-86cf1c522c4c",
      "ticketId": "385e871a-5628-4aa2-a28d-cafe7c876898",
      "walletAddress": "0xe41A4a64564D19f98867a4b43E743a7D988c9d68",
      "walletChain": "INTERNAL",
      "walletMemo": "",
      "txHash": "0x6eec33332c861e2641d9f121e19d52e528d38ca52d92572cd14cefb284bfd643"
    },
    "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 account name and the value of that brCode.

Field	Value	Description
pixKey

00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/fe6d7d3c6d014a9fb9db61cf40a0ee4... | The brCode that needs to be paid |

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=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/fe6d7d3c6d014a9fb9db61cf40a0ee4c5204000053039865802BR5925Ada%20Capital%20Gestao%20de%20Rec6009Sao%20Paulo62070503***6304E066" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "name": "Ada Capital Gestao de Recursos Ltda",
  "taxId": "45.981.761/0001-00",
  "bankName": "STARK BANK S.A.",
  "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	Indicates funds come from the subaccount itself.
outputThirdParty	false	Set to true if the brCode is paid to a third party.
blockchainSendMethod	PERMIT	Specifies that the transfer is automatically handled by Avenia API.
outputBrCode	00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/...	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=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/fe6d7d3c6d014a9fb9db61cf40a0ee4c5204000053039865802BR5925Ada%20Capital%20Gestao%20de%20Rec6009Sao%20Paulo62070503***6304E066" \\
 -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

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": "2ac803ad-faf7-489f-9c1a-c6a64072e699",
    "userId": "05505dde-c2e4-47c5-bd5c-071b4c4bb6a4",
    "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": "0xb6e8860883039b6db937639b94e9a10ff7971bb6"
    },
    "brazilianFiatReceiverInfo": {
      "id": "5f604282-fd2b-4280-9d53-0ceac5d6aada",
      "ticketId": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
      "taxId": "45.981.761/0001-00",
      "userName": "Ada Capital Gestao de Recursos 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": "e20018183202504041630tjwh90ndn86"
    },
    "blockchainSenderInfo": {
      "id": "3186fe63-3c07-4d76-b3d5-6ab3af3117d2",
      "ticketId": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
      "walletAddress": "0xe41A4a64564D19f98867a4b43E743a7D988c9d68",
      "txHash": "0xa85062eca06505fda694a1c23a9938e353b661f1bb7e9f2a3f0fa6c85f8ba765"
    },
    "brlPixOutputInfo": {
      "id": "4edace6f-1fb4-4291-8662-cca72c812d18",
      "ticketId": "7c021079-b8e9-4f4d-9a2e-efcfa72c650c",
      "pixMessage": "",
      "senderAccountBankName": "starkbank",
      "senderAccountNumber": "4790427303542784"
    },
    "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.

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​

HTTP POST Request​

Sample JSON Body​

cUrl Example​

JSON Response​

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

HTTP POST Request

Sample JSON Body

cUrl Example

JSON Response

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