Bank Account COP

Introduction

COP Beneficiary is used as the destination when you transact with COP (Colombian Peso) fiat. A single beneficiary can support two rails:

Rail	Required fields	Use for
PSE (Bank Transfer)	Full bank fields: `bankAccountNumber`, `bankId`, `documentNumber`, address, etc.	Colombian bank-to-bank transfer.
Bre-B	Just `breBKey`	Transfer to any Bre-B-enabled Colombian bank using a key.

You can register a beneficiary with only Bre-B, only bank fields, or both. The rail used at payout time is driven by the quote's outputPaymentMethod:

outputPaymentMethod=BANK-TRANSFER → beneficiary must have bank fields registered
outputPaymentMethod=BRE-B → beneficiary must have breBKey registered

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

Endpoint (same for all 3 registration modes):

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

Required fields (all modes)

Field	Type	Validation Rules	Description
`alias`	string	Max 100 characters; unique per user	A custom name for the beneficiary.
`description`	string	Max 500 characters	Optional description.
`beneficiaryName`	string	Max 140 characters	Full legal name of the recipient.

Mode 1 — Bre-B only (minimal cadastro)

Provide only breBKey alongside the required fields. Avenia validates the key against the Bre-B network before persisting.

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 Bre-B",
  "description": "",
  "beneficiaryName": "Juan Carlos Garcia",
  "breBKey": "@CBW0ZWQT6"
}'

Field	Type	Validation Rules	Description
`breBKey`	string	Max 100 characters	A valid Bre-B key registered to the recipient. Validated at registration time.

Mode 2 — Bank fields only (PSE)

Provide all bank fields. No breBKey.

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

Field	Type	Required when bank fields used	Validation Rules	Description
`beneficiaryType`	string	Yes	`individual` or `business`	Type of account holder.
`beneficiaryEmail`	string	Yes	Valid email	Email of the beneficiary.
`beneficiaryAddress.address1`	string	Yes	—	Street address line 1.
`beneficiaryAddress.address2`	string	No	—	Apartment / suite.
`beneficiaryAddress.country`	string	Yes	Must be `CO`	ISO country code.
`beneficiaryAddress.subDivision`	string	Yes	—	State/Department.
`beneficiaryAddress.city`	string	Yes	—	City name.
`beneficiaryAddress.postalCode`	string	Yes	—	Colombian postal code.
`phoneNumber`	string	Yes	International format	Phone number (e.g. `+573001234567`).
`accountType`	string	Yes	`CHECKING` or `SAVINGS`	Type of bank account.
`bankAccountNumber`	string	Yes	6–18 digits	Bank account number.
`documentNumber`	string	Yes	6–10 digits (Cedula)	Government-issued ID.
`documentType`	string	Yes	`NATIONAL_ID`, `RUC_NIT`, `PASSPORT`, or `RESIDENT_ID`	Document type.
`bankId`	string	Yes	Must be from `/supported-banks`	Bank identifier.
`bankName`	string	Yes	—	Bank name.

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.

info

Partial bank cadastro is rejected. If you provide any bank field (e.g. bankAccountNumber), all bank fields above become mandatory. To register a Bre-B-only beneficiary, leave all bank fields out of the request.

Mode 3 — Both rails (bank + Bre-B)

Combine all bank fields with breBKey. The same beneficiary can then be used for both PSE and Bre-B payouts depending on the quote's outputPaymentMethod.

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 (PSE + Bre-B)",
  "description": "Cuenta + clave Bre-B",
  "beneficiaryName": "Juan Carlos Garcia",
  "beneficiaryType": "individual",
  "beneficiaryEmail": "juan@example.com",
  "beneficiaryAddress": {
    "address1": "Calle 100 #15-20",
    "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",
  "breBKey": "@CBW0ZWQT6"
}'

Common Errors

Error	Cause
`breBKey or bank fields is invalid`	Neither `breBKey` nor any bank field was provided. Provide at least one.
`bankAccountNumber is invalid`	Bank field present but `bankAccountNumber` missing or not 6–18 digits.
`breBKey is invalid`	The provided Bre-B key was not recognised by the Bre-B network (not registered, not active, etc.).

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",
      "breBKey": "@CBW0ZWQT6",
      "createdAt": "2026-02-20T15:13:08.320462Z"
    },
    {
      "id": "ee93dbbb-15a7-401b-88db-0ff12abe5a86",
      "userId": "11111111-1111-1111-1111-111111111111",
      "alias": "Juan Bre-B only",
      "description": "",
      "beneficiaryName": "Juan Carlos Garcia",
      "breBKey": "@CBW0ZWQT6",
      "createdAt": "2026-04-29T16:20:07.466341Z"
    }
  ],
  "cursor": "MzItMTc0MDA2NDM4ODMyMA..."
}

info

Fields not registered for a beneficiary are omitted from the response. A Bre-B-only entry will not include bankAccountNumber, bankId, etc.

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 (omitted for Bre-B-only)
`bankAccounts[].breBKey`	string	Registered Bre-B key (omitted if not registered)
`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 (omitted for Bre-B-only)
`bankAccount.breBKey`	string	Registered Bre-B key (omitted if not registered)
`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 beneficiaries within the Avenia API system.

What we've covered:

✅ Listing Supported Colombian Banks – Retrieve the 44 supported banks and their IDs.
✅ Creating a COP Beneficiary – 3 modes: Bre-B only, bank only (PSE), or both rails.
✅ Fetching All COP Beneficiaries – Retrieve all registered beneficiaries.
✅ Fetching a Specific COP Beneficiary by ID – Retrieve details by UUID.
✅ Deleting a COP Beneficiary – Permanently remove the registration.

By following these steps, you now have full control over your COP beneficiaries within Avenia API. The returned id is used as beneficiaryCopBankAccountId when creating COP payout tickets — Avenia routes the payout via PSE or Bre-B based on the quote's outputPaymentMethod and what the beneficiary supports.

Introduction​

Supported Banks​

HTTP GET Request​

JSON Response​

Response Fields Explained​

Register a COP Beneficiary Account​

Required fields (all modes)​

Mode 1 — Bre-B only (minimal cadastro)​

Mode 2 — Bank fields only (PSE)​

Mode 3 — Both rails (bank + Bre-B)​

Common Errors​

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

Required fields (all modes)

Mode 1 — Bre-B only (minimal cadastro)

Mode 2 — Bank fields only (PSE)

Mode 3 — Both rails (bank + Bre-B)

Common Errors

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