Bank Account COP

Introduction

COP Bank Account is used as the destination bank account when you transact with COP (Colombian Peso) fiat. In order to send money to a Colombian bank account, you need to register it here first as a beneficiary and then reference it in tickets that involve COP transactions.

info

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

warning

COP bank transfers are irreversible once executed — ensure beneficiary details are correct before creating a payout ticket.

Supported Banks

Before registering a beneficiary, retrieve the list of supported Colombian banks:

HTTP GET Request

Endpoint:

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/cop/supported-banks

cURL Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/cop/supported-banks" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "banks": [
    { "bankId": "bank_cop_022", "bankName": "BANCOLOMBIA" },
    { "bankId": "bank_cop_007", "bankName": "BANCOLOMBIA (NEQUI)" },
    { "bankId": "bank_cop_001", "bankName": "BANCAMIA S.A." }
  ]
}

Response Fields Explained

Field	Type	Description
`banks`	array	List of supported Colombian banks (44 banks)
`banks[].bankId`	string	Unique bank identifier — use this when creating a beneficiary
`banks[].bankName`	string	Human-readable bank name

info

Bank IDs use the format bank_cop_XXX (e.g. bank_cop_022 for Bancolombia). Always use the bankId returned by this endpoint — do not construct bank IDs manually.

Register a COP Beneficiary Account

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

HTTP POST Request

Endpoint:

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

cURL Example:

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/bank-accounts/cop/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "alias": "Juan Bancolombia",
  "description": "Cuenta principal de Juan en Bancolombia",
  "beneficiaryName": "Juan Carlos Garcia",
  "beneficiaryType": "individual",
  "beneficiaryEmail": "juan@example.com",
  "beneficiaryAddress": {
    "address1": "Calle 100 #15-20",
    "address2": "Apto 501",
    "country": "CO",
    "subDivision": "Cundinamarca",
    "city": "Bogota",
    "postalCode": "110111"
  },
  "phoneNumber": "+573001234567",
  "accountType": "CHECKING",
  "bankAccountNumber": "00123456",
  "documentNumber": "1234567890",
  "documentType": "NATIONAL_ID",
  "bankId": "bank_cop_022",
  "bankName": "BANCOLOMBIA"
}'

Request Fields

Field	Type	Required	Validation Rules	Description
alias	string	Yes	Max 255 characters; must be unique per user	A custom name for the account to help identify it.
description	string	Yes	Max 500 characters	A brief description of the bank account.
beneficiaryName	string	Yes	—	Full legal name of the account holder.
beneficiaryType	string	Yes	`individual` or `business`	Type of account holder.
beneficiaryEmail	string	Yes	Valid email format	Email of the beneficiary.
beneficiaryAddress	object	Yes	See sub-fields below	Beneficiary's address in Colombia.
beneficiaryAddress.address1	string	Yes	—	Street address line 1.
beneficiaryAddress.address2	string	No	—	Street address line 2 (apartment, suite, etc).
beneficiaryAddress.country	string	Yes	Must be `CO`	ISO country code for Colombia.
beneficiaryAddress.subDivision	string	Yes	—	State/Department (e.g. `Cundinamarca`, `Antioquia`).
beneficiaryAddress.city	string	Yes	—	City name.
beneficiaryAddress.postalCode	string	Yes	—	Colombian postal code.
phoneNumber	string	Yes	International format	Phone number with country code (e.g. `+573001234567`).
accountType	string	Yes	`CHECKING` or `SAVINGS`	Type of bank account.
bankAccountNumber	string	Yes	6–18 characters	The bank account number.
documentNumber	string	Yes	6–10 digits (Colombian Cedula)	Government-issued ID number.
documentType	string	Yes	`NATIONAL_ID`, `RUC_NIT`, `PASSPORT`, or `RESIDENT_ID`	Type of identity document.
bankId	string	Yes	Must be from `/supported-banks`	Bank identifier from the supported banks endpoint.
bankName	string	Yes	—	Name of the bank.

warning

Document validation: The documentNumber for Colombian nationals (Cedula de Ciudadanía) must be 6 to 10 digits. Brazilian CPF numbers (11 digits) will be rejected. For business entities, use documentType: "RUC_NIT" with the Colombian NIT number.

Sample JSON Body

{
  "alias": "Juan Bancolombia",
  "description": "Cuenta principal de Juan en Bancolombia",
  "beneficiaryName": "Juan Carlos Garcia",
  "beneficiaryType": "individual",
  "beneficiaryEmail": "juan@example.com",
  "beneficiaryAddress": {
    "address1": "Calle 100 #15-20",
    "address2": "Apto 501",
    "country": "CO",
    "subDivision": "Cundinamarca",
    "city": "Bogota",
    "postalCode": "110111"
  },
  "phoneNumber": "+573001234567",
  "accountType": "CHECKING",
  "bankAccountNumber": "00123456",
  "documentNumber": "1234567890",
  "documentType": "NATIONAL_ID",
  "bankId": "bank_cop_022",
  "bankName": "BANCOLOMBIA"
}

JSON Response

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

Response Fields Explained

Field	Type	Description
`id`	string (UUID)	Unique identifier for this beneficiary account — SAVE THIS for future payout operations

List all COP beneficiaries bank accounts

To get all the COP 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/cop/

Filter Fields

Field	Type	Description
subAccountId	string	The ID of a sub-account. If provided, data will be fetched for the sub-account; leave empty for main account.
createdAfter	int64	Filters results to include only those created after this timestamp.
createdBefore	int64	Filters results to include only those created before this timestamp.
cursor	string	Cursor for pagination. Pass the value from the previous response to retrieve the next set of results.
alias	string	Filters 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/cop/?subAccountId=&createdAfter=1700000000&createdBefore=1800000000&cursor=NEXT_CURSOR&alias=Juan Bancolombia" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "bankAccounts": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "userId": "11111111-1111-1111-1111-111111111111",
      "alias": "Juan Bancolombia",
      "description": "Cuenta principal de Juan en Bancolombia",
      "beneficiaryName": "Juan Carlos Garcia",
      "beneficiaryType": "individual",
      "bankId": "bank_cop_022",
      "bankName": "BANCOLOMBIA",
      "accountType": "CHECKING",
      "bankAccountNumber": "00123456",
      "documentNumber": "1234567890",
      "documentType": "NATIONAL_ID",
      "createdAt": "2026-02-20T15:13:08.320462Z"
    }
  ],
  "cursor": "MzItMTc0MDA2NDM4ODMyMA..."
}

Response Fields Explained

Field	Type	Description
`bankAccounts`	array	Array of COP beneficiary accounts for this user
`bankAccounts[].id`	string (UUID)	Unique account identifier
`bankAccounts[].userId`	string (UUID)	Your user ID (account owner)
`bankAccounts[].alias`	string	The friendly name you assigned
`bankAccounts[].description`	string	The description you provided
`bankAccounts[].beneficiaryName`	string	Full name of the account holder
`bankAccounts[].beneficiaryType`	string	`individual` or `business`
`bankAccounts[].bankId`	string	Bank identifier (e.g. `bank_cop_022`)
`bankAccounts[].bankName`	string	Name of the bank
`bankAccounts[].accountType`	string	`CHECKING` or `SAVINGS`
`bankAccounts[].bankAccountNumber`	string	Bank account number
`bankAccounts[].documentNumber`	string	Beneficiary document number
`bankAccounts[].documentType`	string	Type of identity document
`bankAccounts[].createdAt`	timestamp	ISO 8601 creation date
`cursor`	string	Pagination cursor for next page (only if more results exist)

Pagination

If cursor is present in the response, there are more results available
Pass this cursor value in the next request as a query parameter to fetch the next batch
No cursor in response means you've reached the last page

Get COP beneficiary bank account by ID

To retrieve the details of a specific COP 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/cop/00000000-0000-0000-0000-000000000000

cUrl Example

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

JSON Response

{
  "bankAccount": {
    "id": "00000000-0000-0000-0000-000000000000",
    "userId": "11111111-1111-1111-1111-111111111111",
    "alias": "Juan Bancolombia",
    "description": "Cuenta principal de Juan en Bancolombia",
    "beneficiaryName": "Juan Carlos Garcia",
    "beneficiaryType": "individual",
    "bankId": "bank_cop_022",
    "bankName": "BANCOLOMBIA",
    "accountType": "CHECKING",
    "bankAccountNumber": "00123456",
    "documentNumber": "1234567890",
    "documentType": "NATIONAL_ID",
    "createdAt": "2026-02-20T15:13:08.320462Z"
  }
}

Response Fields Explained

Field	Type	Description
`bankAccount`	object	Wrapper object containing the account details
`bankAccount.id`	string (UUID)	Unique account identifier
`bankAccount.userId`	string (UUID)	Your user ID (account owner)
`bankAccount.alias`	string	The friendly name you assigned
`bankAccount.description`	string	The description you provided
`bankAccount.beneficiaryName`	string	Full name of the account holder
`bankAccount.beneficiaryType`	string	`individual` or `business`
`bankAccount.bankId`	string	Bank identifier
`bankAccount.bankName`	string	Name of the bank
`bankAccount.accountType`	string	`CHECKING` or `SAVINGS`
`bankAccount.bankAccountNumber`	string	Bank account number
`bankAccount.documentNumber`	string	Beneficiary document number
`bankAccount.documentType`	string	Type of identity document
`bankAccount.createdAt`	timestamp	ISO 8601 creation date

Delete COP beneficiary bank Account

To delete a specific COP 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/cop/00000000-0000-0000-0000-000000000000

cUrl Example

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

JSON Response

{}

Status Code: HTTP 200 OK

Response: Empty JSON object - indicates successful deletion

Your COP bank account has been deleted!

Conclusion

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

What we've covered:

✅ Listing Supported Colombian Banks – Retrieve the 44 supported banks and their IDs.
✅ Creating a COP Bank Account – Register a new Colombian bank account for transfers.
✅ Fetching All COP Bank Accounts – Retrieve all your COP bank accounts.
✅ Fetching a Specific COP Bank Account by ID – Retrieve details by UUID.
✅ Deleting a COP Bank Account – Permanently remove a COP bank account.

By following these steps, you now have full control over your COP bank accounts within Avenia API. You can now use the returned beneficiaryCopBankAccountId when creating tickets that involve COP transactions.

Introduction​

Supported Banks​

HTTP GET Request​

JSON Response​

Response Fields Explained​

Register a COP Beneficiary Account​

HTTP POST Request​

Request Fields​

Sample JSON Body​

JSON Response​

Response Fields Explained​

List all COP beneficiaries bank accounts​

HTTP GET Request​

Filter Fields​

cUrl Example:​

JSON Response​

Response Fields Explained​

Pagination​

Get COP beneficiary bank account by ID​

HTTP GET Request​

cUrl Example​

JSON Response​

Response Fields Explained​

Delete COP beneficiary bank Account​

HTTP DELETE Request​

cUrl Example​

JSON Response​

Conclusion​

Introduction

Supported Banks

HTTP GET Request

JSON Response

Response Fields Explained

Register a COP Beneficiary Account

HTTP POST Request

Request Fields

Sample JSON Body

JSON Response

Response Fields Explained

List all COP beneficiaries bank accounts

HTTP GET Request

Filter Fields

cUrl Example:

JSON Response

Response Fields Explained

Pagination

Get COP beneficiary bank account by ID

HTTP GET Request

cUrl Example

JSON Response

Response Fields Explained

Delete COP beneficiary bank Account

HTTP DELETE Request

cUrl Example

JSON Response

Conclusion