Skip to main content

Bank Account

Introduction​

Bank Account is directly linked to your bank account (or let’s keep the PIX example in mind). In order to receive money into your bank account, you need to register it here.

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

Register a Beneficiary Account​

Let’s take a look at the data needed to create your bank account:

HTTP POST Request​

Endpoint:

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

cURL Example:

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/brl/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "alias": "example bank",
  "description": "Creation of my first bank account in Avenia",
  "userName": "Jane Doe",
  "bankCode": "260",
  "branchCode": "1234",
  "accountNumber": "12345678",
  "accountType": "savings",
  "taxId": "12345678901"
}'

Fields​

FieldTypeRequiredValidation Rules
aliasstringYesMaximum 100 characters. Custom name for the account to help identify it.
descriptionstringNoMaximum 255 characters. A brief description of the account.
pixKeystringNo*Valid PIX key format (CPF, CNPJ, email, phone, or random key). *Either pixKey OR all banking fields must be provided.
taxIdstringYes*Valid CPF or CNPJ format. *Required when using banking fields instead of pixKey.
userNamestringYes*Full name of the account holder. *Required when using banking fields instead of pixKey.
bankCodestringYes*Valid bank code (3 or 8 digits). *Required when using banking fields instead of pixKey.
branchCodestringYes*Branch code of the bank account. *Required when using banking fields instead of pixKey.
accountNumberstringYes*Account number of the bank account. *Required when using banking fields instead of pixKey.
accountTypestringYes*Account type. Possible values: checking, payment, savings, salary. *Required when using banking fields instead of pixKey.
info

You can register a beneficiary account in two ways:

Option 1: Using PIX Key If you provide the pixKey field in your JSON request, you do not need to send the other banking fields as the data will be retrieved automatically from the provided pixKey.

Option 2: Using Bank Account Data If you prefer to provide the banking details manually, you must include all required fields: userName, bankCode, branchCode, accountNumber, accountType, and taxId.

Sample JSON Body​

{
  "alias": "example bank",
  "description": "Creation of my first bank account in Avenia",
  "userName": "Jane Doe",
  "bankCode": "260",
  "branchCode": "1234",
  "accountNumber": "12345678",
  "accountType": "savings",
  "taxId": "12345678901"
}

cUrl Example​

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/brl/" -H "Content-Type: application/json" -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -d '{
  "alias": "example bank",
  "description": "Creation of my first bank account in Avenia",
  "userName": "Jane Doe",
  "bankCode": "260",
  "branchCode": "1234",
  "accountNumber": "12345678",
  "accountType": "savings",
  "taxId": "12345678901"
}'

Alternative JSON Body (Using PIX Key)​

If you prefer to use a PIX key instead of providing banking details manually:

{
  "alias": "PIX Account Example",
  "description": "Bank account created using PIX key",
  "pixKey": "12345678901"
}

JSON Response​

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

List all beneficiaries bank accounts​

To get all the bank accounts, let’s use the endpoint below, with filter fields:

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

HTTP GET Request​

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

Filter Fields​

FieldTypeDescription
subAccountIdstringThe ID of a sub-account. If provided, data will be fetched for the sub-account; leave empty for main account.
createdAfterint64Filters results to include only those created after this timestamp.
createdBeforeint64Filters results to include only those created before this timestamp.
cursorstringCursor for pagination. Pass the value from the previous response to retrieve the next set of results.
aliasstringFilters results to include only those with the specified alias.

cUrl Example:​

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/brl/?subAccountId=&createdAfter=1700000000&createdBefore=1800000000&cursor=NEXT_CURSOR&alias=exampleAlias" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response​

{
  "bankAccounts": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "alias": "example bank",
      "description": "Creation of my first bank account in Avenia",
      "userName": "Jane Doe",
      "bankCode": "260",
      "branchCode": "1234",
      "accountNumber": "12345678",
      "accountType": "savings",
      "taxId": "12345678901",
      "createdAt": "2025-02-20T15:13:08.320462Z"
    }
  ],
  "cursor": "MzItMTc0MDA2NDM4ODMyMA..."
}

Get beneficiary bank account by ID​

To retrieve the details of a specific bank account:

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

HTTP GET Request​

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/brl/00000000-0000-0000-0000-000000000000

cUrl Example​

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/brl/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response​

{
  "id": "00000000-0000-0000-0000-000000000000",
  "alias": "example bank",
  "description": "Creation of my first bank account in Avenia",
  "userName": "Jane Doe",
  "bankCode": "260",
  "branchCode": "1234",
  "accountNumber": "12345678",
  "accountType": "savings",
  "taxId": "12345678901",
  "createdAt": "2025-02-20T15:13:08.320462Z"
}

Delete beneficiary bank Account​

To delete a specific bank account:

info

All the endpoints here are applicable to subAccounts, just pass the subAccountId field followed by the subaccount id as the request parameter.

HTTP DELETE Request​

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/brl/00000000-0000-0000-0000-000000000000

cUrl Example​

curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/brl/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Your bank account has been deleted!

Conclusion​

In this section, you have learned how to manage bank accounts within the Avenia API system.

What we’ve covered:

  • ✅ Creating a bank Account – Register a new bank account.
  • ✅ Fetching All bank Accounts – Retrieve all your bank accounts.
  • ✅ Fetching a Specific bank Account by ID – Retrieve details by UUID.
  • ✅ Deleting a bank Account – Permanently remove a bank account.

By following these steps, you now have full control over your bank accounts within Avenia API.