INFINIA - V1 to V2 Migration Guide

Welcome to the V2 of our API! This guide is designed to help you migrate your integration smoothly from V1 to V2. We've structured this guide to walk you through the necessary setup, security configurations, and operational changes.

Setup

This section covers the initial steps to get your V2 account up and running, from setting your password to understanding your account details and managing subaccounts.

Change Password

Upon receiving your new credentials for V2, it is crucial to change your password immediately to secure your account.

Do you want to change your password? You're in the right place. You'll need your current password, and a new one in hand.

HTTP PATCH Request

https://api.sandbox.avenia.io:10952/v2/auth/change-password

Fields

Field	Type	Description
currentPassword	string	Your current password.
newPassword	string	The new password you want to set.
newPasswordConfirm	string	The same new password to confirm it's correct.

Sample JSON Body

{
  "currentPassword": "ThoughtMyPasswordWasStrong",
  "newPassword": "ThisTimeMyPasswordIsStrong",
  "newPasswordConfirm": "ThisTimeMyPasswordIsStrong"
}

Account Info & Account Balance

Account Information displays all data associated with your account, including your Wallets (Avenia API Wallets), which are automatically created when you set up your Business Account. Detailed information on these wallet capabilities will be provided later.

You can retrieve your account information and balances using the following endpoints.

Account Info - HTTP GET Request:

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

Parameters

Field	Type	Description
subAccountId	string	The ID of your sub-account. Instead of fetching data from your main account, it retrieves data from this sub-account.

Sample JSON Response:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "accountInfo": {
    "id": "11111111-1111-1111-1111-111111111111",
    "accountType": "INDIVIDUAL",
    "name": "xxxxx"
  },
  "wallets": [
    {
      "id": "be85cef0-d70a-47cc-9847-9014570efed5",
      "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "chain": "EVM"
    }
  ],
  "pixKey": "11111111-1111-1111-1111-111111111111",
  "brCode": "00020126740014br.gov.bcb.pix01365c2c61a1-134b-4c34-958f-ea3122ac717f0212Avenia Deposit5204000053039865802BR5917Avenia API Ltda6009Sao Paulo621005060000016304DBD5",
  "createdAt": "2025-02-18T17:00:39.854943Z"
}

info

The ID is the id of your account itself

Account Balance - HTTP GET Request

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

Example JSON Response

{
  "balances": {
    "BRLA": "9457.170326",
    "USDC": "0",
    "USDT": "42.07732"
  }
}

Account Statement

All balance changes in your account will be shown in the account statement. This allows you to track every transaction that occurs.

Logs Fields

Field	Type	Description
balanceChange	Number	The amount transacted in the account.
finalBalance	Number	The account balance after the transaction is applied.
description	String	A human-readable explanation describing the reason for the balance change.

HTTP GET Request

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

Note: Remember that you can pass subAccountId as a parameter for the operation to be for the sub account.

Subaccount Management

A Subaccount is a way to manage your clients by separating your main account (Avenia API Main Account or BA) from others. In endpoints that permit subaccount operations, you can simply pass the subAccountId parameter with the UUID of the subaccount. By doing this, you will be operating on behalf of that subaccount.

The diagram shows that multiple accesses can manage subaccounts related to the main account.

Create Subaccount - HTTP POST Request

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

Fields

Field	Type	Description
accountType	string	Type related to this subaccount (INDIVIDUAL)
name	string	Name to facilitate identification of this sub-account up to 64 characters

Sample JSON Body

{
  "accountType": "INDIVIDUAL",
  "name": "jane doe"
}

More endpoints related to a sub-account Read more

Static BR Code

Introduction

The Static BR Code endpoint allows you to generate static QR Codes for receiving Pix payments. These QR Codes can be created with or without a fixed amount and can be associated with your main account or any of your sub-accounts.

This guide will walk you through how to use this endpoint to generate and manage your static BR Codes.

Generate Static BR Code

This endpoint generates a static BR Code. If a BR Code with the same parameters already exists for the account or sub-account, it will be returned. Otherwise, a new one will be created.

Parameters

The parameters should be sent as a query string in the GET request.

Field	Type	Description
subAccountId	string	Optional. The ID of the sub-account from which the BR Code will be generated. If not provided, it will be generated from the main account.
amount	string	Optional. The fixed amount for the BR Code. If zero, the payer is free to set the amount.
referenceLabel	string	A unique identifier for the BR Code, like an external ID. It must be alphanumeric and have a maximum length of 19 characters. This field is required.
additionalData	string	Optional. Additional information that will be displayed to the payer when they scan the QR Code. It has a maximum length of 35 characters.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/static-br-code

JSON Response

{
  "brCode": "00020126580014br.gov.bcb.pix013600000000-0000-0000-0000-000000000000520400005303986540510.005802BR5913Your Name6009SAO PAULO62290525yourUniqueReference6304XXXX"
}

Security

Security is a top priority. This section provides links to our detailed guides on how to secure your account using Multi-Factor Authentication (MFA) and API Keys.

MFA Guide

To can create your API keys, you need to enable Multi-Factor Authentication using TOTP (Time-Based One-Time Password). This adds an extra layer of security by requiring a time-sensitive code generated by your authentication app.

Read more

API Key Management

How to manage your API keys - create, delete, list, and update them. API Keys provide a simple and efficient approach to API authentication, allowing direct control over access without the need for complex renewal flows.

Read more

API Key Guide

How to use the API key and how to authenticate using it. Learn the practical implementation of API key authentication with cryptographic signatures.

Read more

Webhooks

Receive real-time notifications for events in your account. The following guides will help you set up and manage webhooks.

Webhook Management

Learn how to create, edit, and delete webhooks. Webhooks allow you to receive real-time notifications as soon as an operation is executed, eliminating the need for constant polling.

Read more

Verifying Webhook Authenticity

How to make sure that webhooks are coming from Avenia. Learn to verify the digital signature included in each webhook request using our public key to confirm authenticity and data integrity.

Read more

Webhooks Events

How the events work and what data they contain. Understand the different event types like TICKET events and their various statuses throughout the transaction lifecycle.

Read more

Operations

This section will contain the detailed step-by-step flows for replicating your V1 operations in V2.

Once the quote is reviewed and accepted, a ticket is generated. The ticket represents the final commitment to execute the transaction under the quoted terms. It effectively "closes" the quote and initiates the actual operation—locking the rates, reserving liquidity if needed, and launching the underlying process that moves or converts the funds.

Quote

A quote is a calculation that determines how much someone will receive in exchange for a certain amount of money or assets. It provides a fixed or estimated price for a transaction before it happens, allowing users to know the exact cost, fees, and potential variations in value.

About Quote

A quote expiration is 15 seconds! All inputs are URL Parameters as this is a GET endpoint. Either inputAmount or outputAmount must be provided, but not both at the same time.

Input

For input, we can handle both fiat and blockchain transactions.

Fiat currencies can have a maximum of 2 decimal places, while blockchain currencies can have up to 6 decimal places.

• inputCurrency: The currency the user is paying with (e.g., BRL, USD, USDC)
• inputPaymentMethod: The payment method used for the transaction (e.g., PIX, BLOCKCHAIN)
• inputAmount: The amount the user wants to pay/deposit

Output

For output, we also handle both fiat and blockchain transactions.

Just like for input, fiat currencies can have a maximum of 2 decimal places, while blockchain currencies can have up to 6 decimal places.

• outputCurrency: The currency the user wants to receive (e.g., BRL, USD, USDT)
• outputPaymentMethod: The method in which the user wants to receive the funds (e.g., PIX, BLOCKCHAIN)
• outputAmount: The amount the user wants to receive

Markup

Markup allows you to add an extra fee on top of Avenia's standard pricing, giving you control over how much you charge your users for transactions.

• markupFloatingFee: A percentage fee added on top of the transaction (e.g., 0.01 for 1%)
• markupInputFixedFee: A fixed fee applied to the input amount (e.g., 10.00 in all input operation)
• markupOutputFixedFee: A fixed fee applied to the output amount (e.g., 5.00 in all output operation)
• markupCurrency: The currency in which the markup fee will be charged (e.g., BRLA, USDC, USDT)

The markup must be sent to your Avenia Wallet, which belongs to your Business Account (BA) or sub account if applicable.

Send Method

Send Method is only applied to quotes where the input is blockchain. If your input is a blockchain transaction, you must specify the send method to define how the "deposit" will be made.

Permit

You will sign a transaction allowing Avenia to instantly pull the tokens from your wallet, ensuring a seamless and automatic transfer. Since the transaction is executed immediately, the final amount will not change.

Transfer

You will need to proactively send the tokens to your Avenia Wallet. This means Avenia will lock in the value for a certain period of time, which may result in additional costs due to price fluctuations.

Third Party

Here, you will specify whether the input or output of this transaction belongs to the account holder or a third party.

• inputThirdParty: Specify whether the deposit is being made by the account holder or by a third party
• outputThirdParty: Specify whether the withdrawal will be sent to the account holder or to a third party

Table with allowed data

Permitted Currencies and Payment Methods

Currency	Valid Payment Methods
BRL	PIX
BRLA	INTERNAL, POLYGON, MOONBEAM, CELO, GNOSIS
USDC	INTERNAL, POLYGON, MOONBEAM, CELO
USDCe	POLYGON
USDT	INTERNAL, POLYGON, MOONBEAM, CELO

Blockchain Currencies

Currency	Description
BRLA	BRLA token on supported blockchains
USDC	USD Coin (USDC)
USDCe	USD Coin (USDC.e) on certain networks
USDT	Tether (USDT)
ETH	Ethereum (ETH)
GLMR	Moonbeam (GLMR)
POL	Polygon (POL)
TRX	Tron (TRX)

Valid Markup Currencies

Currency	Can be used for Markup?
BRLA	Yes
USDC	Yes
USDT	Yes

INFINIA Operation STEP-BY-STEP

INFINIA Account – BRIDGE

1. Sub-accounts that receive funds in Brazilian Reais (BRL) and convert them to USDC.
2. Transfer those funds from the sub-account to the INFINIA Account – BRIDGE.
3. Transfer USDC tokens from the INFINIA Account – BRIDGE to other wallets.

1 - Receiving money in subaccounts

Create Subaccount - HTTP POST Request

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

Here we will create the sub-account where you will receive the amounts, and create the quote + ticket to operate through this sub account.

Fields

Field	Type	Description
accountType	string	Type related to this subaccount (INDIVIDUAL)
name	string	Name to facilitate identification of this sub-account up to 64 characters

Sample JSON Body

{
  "accountType": "INDIVIDUAL",
  "name": "AMAZON"
}

JSON Response

The response will include the ID linked to the created Sub account.

{
  "id": "c852df87-ac61-4259-8242-6451658dfedb"
}

info

This ID will be used to perform the operations linked to this sub-account! Passing this ID as the request parameter: subAccountId=c852df87-ac61-4259-8242-6451658dfedb

Quote to receive money in this sub account

Here, we’ll pass PIX as the input method, and as the output, we want to receive the token balance in our SUB ACCOUNT AMAZON - INFINIA BRIDGE. Let’s see how this works in practice!

Pass the sub account id in the request parameter to perform this operation on behalf of the subAccount: subAccountId=c852df87-ac61-4259-8242-6451658dfedb

The request will be GET parameters:

Field	Type	Value	Description
inputCurrency	string	BRL	The currency used for payment.
inputPaymentMethod	string	PIX	The payment method used for the transaction.
inputAmount	decimal	100	The amount the user wants to deposit.
outputCurrency	string	USDC	The currency the user wants to receive.
outputPaymentMethod	string	INTERNAL	The method in which the user will receive the funds. Internal means that it will fall with the balance in the subAccount
inputThirdParty	bool	false	Defines if the deposit is from a third party.
outputThirdParty	bool	false	Defines if the withdrawal is sent to a third party.

You will receive a response containing:

• The JWT of the quote, which will be used to create the ticket.
• The data you sent, confirming the details of your request.
• A breakdown of the fees applied, providing transparency on the costs associated with the transaction.

JSON Response

{
  "quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "inputCurrency": "BRL",
	"inputPaymentMethod": "PIX",
	"inputAmount": "565.3",
	"outputCurrency": "USDC",
	"outputPaymentMethod": "INTERNAL",
	"outputAmount": "100",
	"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": "BRL"
		},
		{
			"type": "In Fee",
			"description": "Fees due to input currency and input payment method.",
			"amount": "0.2",
			"currency": "BRL"
		},
		{
			"type": "Conversion Fee",
			"description": "Fees due to conversion from input currency to output currency.",
			"amount": "5.0877",
			"currency": "BRL"
		},
		{
			"type": "Out Fee",
			"description": "Fees due to output currency and output payment method.",
			"amount": "0",
			"currency": "BRL"
		},
		{
			"type": "Gas Fee",
			"description": "Fees due to blockchain transaction costs.",
			"amount": "0",
			"currency": "BRL"
		}
	],
	"basePrice": "5.600137",
	"pairName": "USDCBRL"
}

Closing the ticket to complete the operation to deposit USDC into the sub-account

To finalize the operation, you need to create a ticket using the quoteToken obtained in the previous step. This ticket confirms the transaction and generates a PIX BR Code for payment.

HTTP POST Request

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

info

To execute this operation for the sub-account, remember to pass its ID as a request parameter: subAccountId=c852df87-ac61-4259-8242-6451658dfedb.

Fields

Field	Type	Description
quoteToken	string	The JWT provided in the quote response. It contains all the details of the negotiated transaction.
ticketBlockchainOutput.beneficiaryWalletId	string	The ID of the destination wallet. To deposit into the sub-account's own wallet, use 00000000-0000-0000-0000-000000000000.

Sample JSON Body

{
	"quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"ticketBlockchainOutput": {
		"beneficiaryWalletId": "00000000-0000-0000-0000-000000000000"
	}
}

JSON Response

The response will provide the ticket ID and a brCode to be paid.

{
	"brCode": "00020101021226810014br.gov.bcb.pix2559qr.woovi.com/qr/v2/cob/3de35176-b86c-46cf-8385-d78106e2208052040000530398654042.205802BR5917BRLA_DIGITAL_LTDA6009Sao_Paulo62290525020ca68cad924058a31709fac6304E355",
	"id": "2875bf2c-a9e8-4641-88ad-6aeb22fae41e"
}

info

The generated brCode is valid for 5 minutes. Payment must be made within this timeframe to ensure the transaction is completed sssssssss

{
	"id": "0bb7ca08-9334-45b0-b791-2f385a72b7b5"
}

2 - Transfer those funds from the sub-account to the INFINIA Account – BRIDGE.

First, you need the ID of your main account, which will be the destination for the funds.

info

here we have the money in your sub account, now let's move the money from the sub account to the main INIFNIA BRIDGE account.

Getting your Main Account ID

To get your main account ID, make a GET request to the account-info endpoint without providing a subAccountId. The id field in the response is your main account ID.

HTTP GET Request

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

Sample JSON Response

The id in the root of the object is your main account ID.

{
  "id": "8a618bbc-9d5c-48fa-b5ed-5ee8599bd6e8",
  "accountInfo": {
    "id": "11111111-1111-1111-1111-111111111111",
    "accountType": "BUSINESS",
    "name": "INFINIA BRIDGE"
  },
  "wallets": [
    {
      "id": "be85cef0-d70a-47cc-9847-9014570efed5",
      "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "chain": "EVM"
    }
  ]
}

Quote to transfer funds to the main account

Now, create a quote to transfer USDC from the sub-account's internal balance to the main account's internal balance.

info

This operation is performed on behalf of the sub-account, so you must pass its ID in the request parameters: subAccountId=c852df87-ac61-4259-8242-6451658dfedb.

The request will be GET parameters:

Field	Type	Value	Description
inputCurrency	string	USDC	The currency to be sent from the sub-account.
inputPaymentMethod	string	INTERNAL	The funds will be debited from the sub-account's internal balance.
inputAmount	decimal	100	The amount to transfer.
outputCurrency	string	USDC	The currency to be received in the main account.
outputPaymentMethod	string	INTERNAL	The funds will be credited to the main account's internal balance.
blockchainSendMethod	string	PERMIT	Defines how the transfer is authorized.
inputThirdParty	bool	false	The source is not a third party.
outputThirdParty	bool	false	The destination is not a third party.

You will receive a response with the quoteToken to be used for the ticket.

Closing the ticket to complete the transfer

Finally, create a ticket using the quoteToken to execute the internal transfer to your main account.

HTTP POST Request

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

info

To execute this operation for the sub-account, remember to pass its ID as a request parameter: subAccountId=c852df87-ac61-4259-8242-6451658dfedb.

Sample JSON Body

{
	"quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"ticketBlockchainOutput": {
		"beneficiaryWalletId": "8a618bbc-9d5c-48fa-b5ed-5ee8599bd6e8"
	}
}

JSON Response

The response will contain the ID of the created ticket, confirming the transfer.

{
	"id": "0bb7ca08-9334-45b0-b791-2f385a72b7b5"
}

That's it! The funds have been sent from the AMAZON sub-account to the INFINIA BRIDGE main account.

3 - Transfer USDC tokens from the INFINIA Account – BRIDGE to other wallets

Before you can transfer funds to an external wallet, you need to register it as a beneficiary in the Avenia system.

Beneficiary Wallets

Beneficiary Wallets are wallets that exist outside the Avenia API ecosystem. You can register any external wallet to your business account (or sub-account) to use in future operations.

Create Beneficiary Wallet

To register a new beneficiary wallet, make a POST request to the following endpoint.

HTTP POST Request

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/

Sample JSON Body

{
  "alias": "My External Wallet",
  "description": "My personal hot wallet for USDC",
  "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "walletChain": "POLYGON",
  "walletMemo": "optional-memo"
}

JSON Response

The response will contain the unique ID for the newly registered beneficiary wallet. This ID will be used in future transfer operations.

{
  "id": "76971925-a1ca-423f-badf-0b3f2b03c51c"
}

For more details on managing beneficiary wallets, such as listing, updating, or deleting them, please refer to our full guide: Wallet's Guide.

Quote to send funds to a beneficiary wallet

Now, let's create a quote to send USDC from your main account's internal balance to the external beneficiary wallet.

This operation is performed from your main account, so no subAccountId is required.

The request will be:

Field	Type	Value	Description
inputCurrency	string	USDC	The currency to send from your main account.
inputPaymentMethod	string	INTERNAL	The funds will be debited from your internal balance.
inputAmount	decimal	100	The amount to transfer.
outputCurrency	string	USDC	The currency the beneficiary will receive.
outputPaymentMethod	string	POLYGON	The blockchain network for the withdrawal.

You will receive a response containing the quoteToken needed to create the ticket.

Closing the ticket to complete the withdrawal

Finally, create the ticket using the quoteToken and the beneficiaryWalletId of the wallet you registered.

HTTP POST Request

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

Sample JSON Body

The beneficiaryWalletId should be the ID of the external wallet you created in the previous step.

{
	"quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"ticketBlockchainOutput": {
		"beneficiaryWalletId": "76971925-a1ca-423f-badf-0b3f2b03c51c"
	}
}

JSON Response

The response will contain the ID of the created ticket, confirming the withdrawal has been initiated.

{
	"id": "550e8400-e29b-41d4-a716-446655440000"
}

And that's it! The funds have been sent from your INFINIA BRIDGE main account to the registered beneficiary wallet.