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"
}'

Fields​

FieldTypeDescription
aliasstringA custom name for the account to help identify it.
descriptionstringA brief description of the wallet.
userNamestringThe full name of the account holder.
bankCodestringThe bank’s code where the account is registered.
branchCodestringThe branch code of the bank account.
accountNumberstringThe account number of the bank account.
accountTypestringThe type of account. Possible values: checking, payment, savings, salary.
taxIdstringThe taxpayer identification number. Possible formats: CPF, CNPJ, or other valid tax identification numbers.
info

If you provide the pixKey field in your JSON request, you do not need to send the other fields as the data will be retrieved automatically from the provided pixKey.

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"
}

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"
}'

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",
      "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",
  "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.