Bank Account - BRL

Introduction

The Bank Account - BRL establishes a connection between the traditional Brazilian Real (BRL) payment system and blockchain systems, acting as a bridge for seamless transactions.

This section will guide you through providing visibility of the Bank Account - BRL within Avenia API for efficient and secure integrations.

Bank Account - BRL Initialization

The initialization of your Bank Account - BRL is performed during the creation of your Business Account (BA). Upon creating your Business Account, a fiat rail is automatically initialized along with Avenia wallets by default. You will have visibility of these details in the following sections.

Get Bank Account - BRL Information

Since Bank Account - BRL was initialized during the creation of your business account, we will now retrieve this information.

HTTP GET Request

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

cURL Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "ACTIVE",
  "bankName": "Example Bank",
  "pixKey": "11111111-1111-1111-1111-111111111111",
  "ispb": "00000000",
  "bankCode": "000",
  "branchCode": "0000",
  "accountNumber": "0000000000000000",
  "accountType": "payment",
  "createdAt": "2025-03-10T15:23:17.801357Z"
}

note

This endpoint returns the main-account-level BRL rail. To retrieve the deposit PIX key and BR Code of a specific account or sub-account, use GET /v2/account/account-info, which accepts a subAccountId and returns the pixKey and a per-account/sub-account brCode. When you need to tell apart deposits from different sub-accounts, use the sub-account's brCode — the pixKey is shared across the Business Account.

Get a Sub-Account's Deposit PIX Key & BR Code

Each sub-account can receive BRL deposits. To fetch a sub-account's deposit pixKey and its unique brCode, call the Account Info endpoint with the sub-account's subAccountId.

Parameters

Field	Type	Description
subAccountId	string	The sub-account to fetch. Omit it to retrieve the main account's deposit information instead.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/account-info?subAccountId=<SUB_ACCOUNT_ID>

cURL Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/account-info?subAccountId=00000000-0000-0000-0000-000000000000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "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"
}

Field	Type	Description
pixKey	string	BRL deposit PIX key. Shared across the whole Business Account (same for every sub-account).
brCode	string	PIX copy-and-paste (QR) code, unique per account/sub-account. Use it to identify which sub-account a deposit belongs to.

tip

Prefer the brCode for deposit reconciliation: since the pixKey is shared, the per-sub-account brCode is what lets you attribute an incoming deposit to a specific sub-account.

Get Pix Info

The Pix Info endpoint provides information about the owner of a Pix key and their associated bank. It supports both Pix keys (e.g., CPF, email, phone number) and BR Codes.

Parameters

Field	Type	Description
pixKey	string	Here a BrCode or Pix Key that you would like to know more about
decodePixKey	bool	If the pixKey field is a pixKey, and you want to collect more information from this pixKey, pass this field as true

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=00000000000&decodePixKey=true" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "name": "Herminia Kloth",
  "taxId": "***.317.608-**",
  "bankName": "Herminia Kloth",
  "ispb": "00000000",
  "amount": ""
}

Field	Type	Description
name	string	Account holder's name
taxId	string	Account holder's tax ID (partially masked)
bankName	string	Human-readable name of the counterparty bank
ispb	string	The 8-digit ISPB code identifying the counterparty bank. Use it to cross-check against the blocked institutions list before creating a pay-out ticket
amount	string	Amount encoded in the BR Code, when present (empty for plain Pix keys)

Conclusion

In this section, you have learned how to interact with the Bank Account - BRL within Avenia API:

• ✅ Retrieving Bank Account - BRL Information – Obtaining initialized bank account details.
• ✅ Getting Pix Info – Retrieving detailed information related to a Pix key or BR Code.

You now have the necessary understanding to handle BRL fiat rails effectively.