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.
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
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"
}
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. |
Endpoint
Request 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"
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": "00020126580014br.gov.bcb.pix013600000000-0000-0000-0000-0000000000005204000053039865802BR5915Avenia API Ltda6009SAO PAULO62070503***6304XXXX",
"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. |
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 | true runs the lookup in the Central Bank's Pix directory (DICT), which returns the key holder (name, taxId, bankName, ispb), for both Pix keys and BR Codes. Without it, only the data encoded in the BR Code itself (amount, expiration) is returned |
| subAccountId | string | Optional. The sub-account (end user) making the lookup. DICT lookups are rate-limited per user, so pass it to charge the lookup to that sub-account instead of the main account |
With decodePixKey, each lookup counts against the DICT rate limit of the account or sub-account making it. When the limit is reached, the endpoint returns HTTP 429. See DICT Lookup Limits.
Only the presence of decodePixKey is checked: decodePixKey=false also triggers a lookup. To skip it, leave the parameter out.
Endpoint
Request 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"
Response
{
"name": "Herminia Kloth",
"taxId": "***.456.789-**",
"bankName": "Herminia Kloth",
"ispb": "00000000",
"amount": ""
}
| Field | Type | Description |
|---|---|---|
name | string | Account holder's name |
taxId | string | Account holder's tax ID, as returned by the DICT: CNPJ in full, CPF partially masked (see below) |
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) |
expiration | string | Expiration of a dynamic BR Code (omitted otherwise) |