> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bre-B（哥伦比亚）

Bre-B 是哥伦比亚的国家实时支付渠道，由 Banco de la República 运营。通过虚拟账户密钥全天候接受即时 A2A 收款（payin），并可将资金直接发送至任意 Bre-B 密钥（payout）——全部通过一次集成实现。

**Bre-B** 是哥伦比亚首个由政府强制推行的实时支付渠道，由 Banco de la República 于 2025 年 10 月 6 日正式上线。该国所有持牌银行、电子钱包和支付服务提供商首次共享同一套即时、可互操作的基础设施——就像 [Pix](https://docs.localpayment.com/zh/docs/pix-brazil.md) 改变了巴西一样。

Bre-B 提供 20 秒内即可完成的即时账户间转账 (A2A) 服务，全年 365 天、每天 24 小时全天候可用，并支持基于别名的支付方式（称为 *llaves*），无需提供完整的账号。所有受监管的金融机构都必须参与 Bre-B，这使得 Bre-B 成为哥伦比亚有史以来发展最快的支付渠道。

Localpayment 同时支持通过 Bre-B **接收**和**发送**付款：

| 流程 | 方法 | 支付代码 | 币种 | 最大金额 |
| - | - | - | - | - |
| **收款**（接收） | 虚拟账户 | `2006` | COP | 12,110,000 哥伦比亚比索 |
| **付款**（发送） | 银行转账 | `0062` | COP | 11,552,000 哥伦比亚比索 |

***

## 概述

### Bre-B 与 PSE：何时使用哪种？

哥伦比亚已将 [PSE](https://docs.localpayment.com/zh/docs/pse-colombia.md) 作为成熟的 A2A 支付方式。Bre-B 并非取代 PSE，而是提供了一种更快、更便捷的替代方案。请使用下表选择适合您使用场景的支付方式：

| 功能 | PSE | Bre-B |
| - | - | - |
| **结算** | 批次周期——取决于银行的截止时间 | 即时、随时随地——无需清算延迟 |
| **可用性** | 仅限银行营业时间（通常为周一至周五，上午 8 点至下午 5 点） | 全天候 24/7/365 服务，包括夜间、周末和节假日 |
| **结账体验** | 需要完整账户信息 + 银行跳转 | 无需跳转——付款方使用别名（*llave*）或二维码 |
| **互操作性** | 仅限参与银行，流程各异 | 所有持牌银行、电子钱包和支付服务提供商都必须遵守 |
| **确认速度** | 根据时间安排，可能需要数小时到数天不等 | 保证在 20 秒内 |
| **非常适合** | 已集成 PSE 的成熟流程 | 全新集成、实时用例、全天候服务 |

### Bre-B 密钥（Llave）

*llave*（密钥）是一个简短的字母数字别名，用于代替 Bre-B 转账中的完整银行账号。付款人只需在银行应用程序中输入密钥即可，无需提供完整的账户信息。

**Localpayment 如何生成您的密钥**

当您为哥伦比亚创建虚拟账户时，Localpayment 会自动生成一个**字母数字密钥**——您无需选择或配置密钥类型。该密钥会根据您提供的收款人姓名自动生成：

| 部分 | 内容 | 描述 |
| - | - | - |
| **1** | `LP` | 固定前缀，表示密钥由 Localpayment 签发。 |
| **2** | 最多 10 个字母数字字符 | 去除空格和特殊字符（例如 `-`、`.`、重音符号）后得到的受益人姓名的前几个字符。 |
| **3** | 4 位顺序计数器 | 每签发一个密钥便递增的补零计数器（例如 `0001`、`0002`、`0003`）。 |

**密钥总长度**：10 到 16 个字母数字字符（不含 `@` 前缀符号）。

**示例**——受益人姓名为 `"TechColombia SAS"`：

1. 去除空格和特殊字符 → `TechColombiaSAS`
2. 取前 10 个字母数字字符 → `TechColomb`
3. 组合 → `@` + `LP` + `TechColomb` + `0001` = **`@LPTechColomb0001`**（16 个字符）

虚拟账户激活后（`status.code: "200"`），生成的密钥会在 `beneficiary.bank.account.number` 中返回。

### 限制与可用性

| 属性 | 收款（代码 `2006`） | 付款（代码 `0062`） |
| - | - | - |
| 币种 | `COP` | `COP` |
| 最低金额 | 1.00 哥伦比亚比索 | 1.00 哥伦比亚比索 |
| 最高金额 | 12,110,000.00 哥伦比亚比索 | 11,552,000.00 哥伦比亚比索 |
| 结算速度 | 实时（\< 20 秒） | 实时（\< 20 秒） |
| 可用性 | 24/7/365 | 24/7/365 |
| 付款确认 | 异步（webhook） | 异步（webhook） |

### 演示

看看付款方在实际操作中如何使用 Bre-B 虚拟账户：

[嵌入内容](https://embed.figma.com/proto/4RwikYTlBaLleedifW2WcO/Virtual-Accounts-Examples?node-id=7395-59\&scaling=scale-down-width\&content-scaling=fixed\&page-id=7395%3A185\&embed-host=share\&kind=proto)

***

## 接收 Bre-B 付款（Payin）

通过 Bre-B 收款（Payin）使用 **[虚拟账户](https://docs.localpayment.com/zh/docs/virtual-accounts-overview.md)** 基础设施。Localpayment 会为您创建的每个账户生成一个唯一的 Bre-B 字母数字密钥。付款人可以通过任何支持 Bre-B 的银行应用程序向该密钥汇款。结算即时完成，并且完全自动化。

### 工作原理

1. 创建虚拟账户：您的系统使用受益人详细信息调用创建虚拟账户 endpoint。
2. 获取 Bre-B 密钥：账户激活后（约 6 秒），查询其状态，从 `beneficiary.bank.account.number` 获取系统生成的密钥。
3. 将密钥分享给付款人：付款人在其银行应用程序中输入密钥以发起转账。
4. 接收资金和 webhook：Localpayment 接收转账并向您配置的 endpoint 发送实时 webhook。

### 开始之前

请确保您已备好：

* 有效的 [API 凭证](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)（访问令牌）。
* 已为[哥伦比亚](https://docs.localpayment.com/zh/docs/colombia.md)（`COP`）配置的 Localpayment 账户。

***

### 第一步：创建虚拟账户

向[创建虚拟账户](https://docs.localpayment.com/zh/reference/create-virtual-account.md)endpoint 发送 `POST` 请求。

#### 关键请求参数

| 参数 | 类型 | 必需的 | 描述 | 例子 |
| - | - | - | - | - |
| `country` | string | ✅ | 哥伦比亚必须为 `COL`。 | `"COL"` |
| `accountNumber` | string | ✅ | 您的Localpayment商户账号。 | `"{{accountNumber}}"` |
| `externalId` | string | ✅ | 这是您此虚拟账户的唯一标识符。请使用 UUID。 | `"a1b2c3d4-..."` |
| `beneficiary.type` | string | ✅ | `INDIVIDUAL`（个人）或 `COMPANY`（法人实体）。 | `"COMPANY"` |
| `beneficiary.name` | string | ✅ | 全名或法人实体名称。前几个字符用于生成 Bre-B 密钥。 | `"TechColombia SAS"` |
| `beneficiary.document.type` | string | ✅ | 公司使用 `NIT`；个人使用 `CC`、`CE`、`TI` 或 `PASS`。 | `"NIT"` |
| `beneficiary.document.id` | string | ✅ | 与所选证件类型格式相符的证件号码。 | `"901275418-3"` |

请参阅 API 参考，了解[所有可用参数](https://docs.localpayment.com/zh/reference/create-virtual-account.md)。

#### 示例请求

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/virtual-account \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "country": "COL",
  "accountNumber": "{{accountNumber}}",
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "beneficiary": {
    "type": "COMPANY",
    "name": "TechColombia SAS",
    "document": {
      "type": "NIT",
      "id": "901275418-3"
    }
  }
}'
```

#### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "internalId": "8f3e1c20-4b72-4d5a-9a1b-2c3d4e5f6078",
  "accountNumber": "{{accountNumber}}",
  "country": "COL",
  "currency": "COP",
  "beneficiary": {
    "type": "COMPANY",
    "name": "TechColombia SAS",
    "fullName": "TechColombia SAS",
    "lastName": "",
    "document": {
      "type": "NIT",
      "id": "901275418-3"
    }
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "Virtual account in progress"
  },
  "errors": []
}
```

#### 错误响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "internalId": "f2d9d9b0-093d-469b-c8d6-728b0cc67e80",
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [document.id] + verification failed"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [document.id] + verification failed"
    }
  ]
}
```

> [!NOTE]
>
> **激活时间**：哥伦比亚虚拟账户通常会在 **6 秒**内激活。轮询状态 endpoint 或稍等片刻后再检索 Bre-B 密钥。

> [!NOTE]
>
> **非本地受益人**
>
> 如果您的收款人是外国居民（非哥伦比亚本地居民），则虚拟账户必须以账户持有人的身份在 Localpayment 注册。这既能确保符合当地银行法规，又能让您代表外国实体接收付款。

***

### 步骤 2：获取您的 Bre-B 密钥

虚拟账户激活后（`status.code: "200"`），向[获取虚拟账户状态](https://docs.localpayment.com/zh/reference/get-virtual-account-status.md)endpoint 发送 `GET` 请求。

#### 示例请求

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request GET \
     --url 'https://api.stage.localpayment.com/api/virtual-account/a1b2c3d4-5e6f-7890-abcd-ef1234567890' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json'
```

#### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "internalId": "8f3e1c20-4b72-4d5a-9a1b-2c3d4e5f6078",
  "accountNumber": "{{accountNumber}}",
  "country": "COL",
  "currency": "COP",
  "beneficiary": {
    "type": "COMPANY",
    "name": "TechColombia SAS",
    "fullName": "TechColombia SAS",
    "lastName": "",
    "document": {
      "type": "NIT",
      "id": "901275418-3"
    },
    "bank": {
      "account": {
        "type": "KEY",
        "number": "@LPTechColomb0001"
      }
    }
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "Virtual account active and ready for payments"
  },
  "errors": []
}
```

#### 关键响应字段

| 字段 | 描述 |
| - | - |
| `beneficiary.bank.account.number` | 要与付款方共享的 Bre-B 密钥（例如 `@LPTechColomb0001`）。 |
| `beneficiary.bank.account.type` | Bre-B 虚拟账户始终为 `KEY`。 |
| `status.code` | `200` = 已激活并可接收付款。`100` = 仍在激活中。 |

将 `beneficiary.bank.account.number` 的值分享给付款方。无需提供其他银行账户信息。

***

### 步骤 3：付款方发起转账

付款方在任何参与的哥伦比亚银行应用程序或数字钱包中使用 Bre-B 密钥：

1. 打开银行应用程序，选择 Bre-B 或**按密钥转账**选项。
2. 输入 Bre-B 密钥（例如 `@LPTechColomb0001`）作为收款目标。
3. 输入金额并确认转账。
4. 支付将在 20 秒内完成。

Localpayment 会自动将收到的付款与您的虚拟账户进行匹配，并发送 webhook。

***

### 第四步：处理 Webhook

付款入账后，Localpayment 会向您配置的 endpoint 发送 `POST` 请求。您的服务器必须返回 `HTTP 200 OK` 以确认接收。有关设置说明，请参阅 [Webhooks 指南](https://docs.localpayment.com/zh/docs/webhooks.md)。

#### Webhook 载荷示例

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "transactionType": "PayIn",
    "externalId": "cf194632-7ec4-4a44-9b92-9bbacad5349a",
    "internalId": "b97ac13c-1acb-4bc0-8b2a-067945e26161",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "2006",
        "flow": "DIRECT"
    },
    "country": "COL",
    "currency": "COP",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
        "currency": "COP",
        "fxQuote": 1.0,
        "amount": 1000.0
    },
    "payment": {
        "currency": "COP",
        "fxQuote": 1.0,
        "financingFee": 0.0,
        "amount": 1000.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "COP",
        "fxSource": 3705.82,
        "fxQuote": 1.0,
        "amount": 1.0,
        "account": "{{accountNumber}}"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "COMPANY",
        "name": "LOCALPAYMENT",
        "document": {
            "type": "NIT",
            "id": "1111123456"
        },
        "bank": {
            "name": "BANCO DE BOGOTÁ",
            "code": "1001",
            "account": {
                "type": "KEY",
                "number": "@XXXXXXXOXX0000"
            }
        }
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Test company"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastName": "Doe",
        "document": {
            "type": "CC",
            "id": "11111654321"
        },
        "email": "NA",
        "bank": {
            "name": "BANCO POPULAR",
            "code": "1002",
            "account": {
                "type": "BREB",
                "number": "signer:wTUTnHK5mLAQXLgVuhoANKGaKTdgRFmrx7@breb"
            }
        }
    },
    "date": {
        "creationDate": "2026-02-25T18:53:25Z",
        "processedDate": "2026-02-25T18:53:26Z"
    },
    "errors": [],
    "referenceCode": "V0ZO-AIPV-NOD9",
    "tracking": {
        "id": "20260225900504001TFY123451234501234",
        "reference": "20260225900504001TFY123451234501234",
        "concept": "Test payment"
    }
}
```

#### 关键 Webhook 字段

| 字段 | 描述 |
| - | - |
| `paymentMethod.code` | Bre-B 虚拟账户收款始终为 `2006`。 |
| `status.code` | `200` = `COMPLETED`——资金已入账。 |
| `beneficiary.bank.account.number` | 您的虚拟账户中收到付款的 Bre-B 密钥。 |
| `payer.bank.account.type` | `BREB`——确认付款方通过 Bre-B 网络发送。 |
| `tracking.id` / `tracking.reference` | Bre-B 网络交易参考号。用于[对账](https://docs.localpayment.com/zh/docs/reporting-and-reconciliation.md)。 |
| `tracking.concept` | 付款方提供的转账说明。 |
| `referenceCode` | Localpayment 为此笔交易提供的唯一参考编号。 |

***

### 第五步：跟踪收款状态

> [card] [Webhooks（推荐）](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 款项到账后即可收到实时通知。在生产环境中最为高效。

> [card] [状态 API endpoint](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 通过编程方式查询交易状态。可用于核对错过的 webhook 通知。

> [card] [Business Portal 视图](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 用于监控交易的可视化界面。非常适合人工监督和详细分析。

Bre-B 是一种实时直接支付渠道——交易即时结算。只有在款项完全到账后才会发送 webhook。

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `200` | `COMPLETED` | 款项已存入您的账户。 |

> [!NOTE]
>
> **完整参考**
>
> 请在我们的[交易状态文档](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)中查看所有状态码。

***

## 发送 Bre-B 付款（Payout）

要向收款方的 Bre-B 密钥发送资金，请使用 **[银行转账付款](https://docs.localpayment.com/zh/docs/send-funds-via-bank-transfer.md)** 流程，支付方式代码为 `0062`。收款方必须已在其银行注册 Bre-B 密钥。您需通过 `beneficiary.bank.account.alias` 提供该密钥。

### 工作原理

1. 收集收款方的 Bre-B 密钥：获取收款方已注册的 llave（任何支持的密钥类型：字母数字、电话号码、电子邮件、证件或商户代码）。
2. 提交付款：使用代码 `0062` 调用创建付款 endpoint，并在 `beneficiary.bank.account.alias` 中传入密钥。
3. 跟踪转账：通过 Webhook 或状态 API 监控状态，直至 `200 Completed`。

***

### 第一步：发起付款

向[创建付款](https://docs.localpayment.com/zh/reference/create-a-payout.md)endpoint 发送 `POST` 请求。请注意，请求体是一个**数组**。

#### 关键请求参数

| 参数 | 类型 | 必需的 | 描述 | 例子 |
| - | - | - | - | - |
| `country` | string | ✅ | 必须是 `COL`。 | `"COL"` |
| `currency` | string | ✅ | 必须是 `COP`。 | `"COP"` |
| `amount` | number | ✅ | 交易金额。最低 1.00 哥伦比亚比索，最高 11,552,000.00 哥伦比亚比索。 | `50000` |
| `paymentMethod.type` | string | ✅ | 必须是 `BankTransfer`。 | `"BankTransfer"` |
| `paymentMethod.code` | string | ✅ | Bre-B 必须是 `0062`。 | `"0062"` |
| `paymentMethod.flow` | string | ✅ | 必须是 `DIRECT`。 | `"DIRECT"` |
| `beneficiary.type` | string | ✅ | `INDIVIDUAL` 或 `COMPANY`。 | `"INDIVIDUAL"` |
| `beneficiary.name` | string | ✅ | 收款方的名字或公司名称。 | `"John"` |
| `beneficiary.lastName` | string | ✅ | 收款方的姓氏（仅限个人）。 | `"Doe"` |
| `beneficiary.document.type` | string | ✅ | `CC`、`NIT`、`CE`、`TI` 或 `PASS`。 | `"CC"` |
| `beneficiary.document.id` | string | ✅ | 与所选证件类型格式相符的证件号码。 | `"1088338888"` |
| `beneficiary.bank.account.alias` | string | ✅ | 收款方已注册的 Bre-B 密钥（llave）。**请勿**包含 `account.type` 或 `account.number`。 | `"@juanPerez0001"` |
| `accountNumber` | string | ✅ | 您的Localpayment商户账号。 | `"{{accountNumber}}"` |
| `externalId` | string | ✅ | 本次付款的唯一标识符。请使用 UUID。 | `"b2c3d4e5-..."` |
| `conceptCode` | string | ✅ | Localpayment 提供的付款用途代码。 | `"0001"` |

> [!WARNING]
>
> **重要提示**：向 Bre-B 密钥付款时，请求中必须**排除** `beneficiary.bank.account.type` 和 `beneficiary.bank.account.number` 字段，仅使用 `beneficiary.bank.account.alias`。

#### 示例请求

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/payout/ \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '[
  {
    "externalId": "b2c3d4e5-6f7a-8901-bcde-f12345678901",
    "country": "COL",
    "currency": "COP",
    "amount": 50000,
    "paymentMethod": {
      "type": "BankTransfer",
      "code": "0062",
      "flow": "DIRECT"
    },
    "beneficiary": {
      "type": "INDIVIDUAL",
      "name": "John",
      "lastName": "Doe",
      "document": {
        "type": "CC",
        "id": "1088338888"
      },
      "email": "john.doe@example.com",
      "bank": {
        "account": {
          "alias": "@juanPerez0001"
        }
      }
    },
    "sender": {
      "type": "COMPANY",
      "name": "TechColombia SAS",
      "document": {
        "type": "NIT",
        "id": "901275418-3"
      },
      "email": "pagos@techcolombia.com"
    },
    "merchant": {
      "type": "COMPANY",
      "name": "TechColombia SAS",
      "document": {
        "type": "NIT",
        "id": "901275418-3"
      }
    },
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "comment": "Pago Bre-B Colombia"
  }
]'
```

#### 成功响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "b2c3d4e5-6f7a-8901-bcde-f12345678901",
    "internalId": "3a4b5c6d-7e8f-9012-cdef-a12345678902",
    "paymentMethod": {
        "code": "0062",
        "name": "Bre-B Key",
        "paymentMethodType": "BankTransfer"
    },
    "country": "COL",
    "currency": "COP",
    "amount": 50000,
    "accountNumber": "{{accountNumber}}",
    "status": {
        "code": "100",
        "description": "Received",
        "detail": "The payout was received"
    },
    "beneficiary": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "CC",
            "id": "1088338888"
        },
        "email": "john.doe@example.com",
        "bank": {
            "account": {
                "alias": "@juanPerez0001"
            }
        }
    },
    "date": {
        "creationDate": "2026-02-25T18:53:25Z",
        "processedDate": "2026-02-25T18:53:26Z"
    },
    "errors": null
}
```

#### 错误响应

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "externalId": "b2c3d4e5-6f7a-8901-bcde-f12345678901",
    "internalId": "cd052d8c-8406-45f8-98aa-aff9876c3285",
    "status": {
      "code": "801",
      "description": "Rejected",
      "detail": "Params error"
    },
    "errors": [
      {
        "code": "300",
        "description": "Invalid param + [paymentMethod.code] + doesn't exist for PAYMENT_METHOD_TYPE BankTransfer"
      }
    ]
  }
]
```

***

### 步骤 2. 跟踪付款状态

> [card] [Webhooks（推荐）](https://docs.localpayment.com/zh/docs/webhooks.md)
>
> 转账扣款时接收实时通知。最适用于生产环境。

> [card] [状态 API endpoint](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 通过编程方式查询付款状态。这对于对账和异常处理非常有用。

> [card] [Business Portal 视图](https://docs.localpayment.com/zh/docs/dashboard-overview.md)
>
> 用于监控和手动批准付款的可视化界面。

| 代码 | 状态 | 描述 |
| :- | :- | :- |
| `100` | `Received` | Localpayment已收到款项。 |
| `101` | `Locked` | 已确认并通过反洗钱验证。 |
| `102` | `In Progress` | 已发送至 Bre-B 网络。 |
| `200` | `Completed` | 款项已记入收款人账户。 |
| `300` | `Rejected` | 参数无效——请查看 `errors` 数组了解详情。 |

> [!NOTE]
>
> **完整参考**
>
> 请在我们的[交易状态文档](https://docs.localpayment.com/zh/reference/transaction-status-error-codes)中查看所有状态码。

***

## 支持的银行

Bre-B 付款可以在所有参与的哥伦比亚金融机构之间发送和接收——200 多家银行、数字钱包和与哥伦比亚共和国银行网络连接的合作社。

> [accordion] 完整银行列表
>
> > [tab] A
> >
> > * A\&C COLANTA
> > * ACCIONES Y VALORES
> > * AFROAMERICANA
> > * ALCALICOOP
> > * AMAR
> > * AVANCOP
>
> > [tab] B
> >
> > * BADIVENCOOP
> > * BAN100
> > * BANCAMIA S A
> > * BANCO AGRARIO
> > * BANCO AV VILLAS
> > * BANCO BTG PACTUAL
> > * BANCO CAJA SOCIAL
> > * BANCO CONTACTAR
> > * BANCO DAVIVIENDA
> > * BANCO DE BOGOTA
> > * BANCO DE OCCIDENTE
> > * BANCO FALABELLA
> > * BANCO FINANDINA
> > * BANCO ITAÚ
> > * BANCO MUNDO MUJER
> > * BANCO POPULAR
> > * BANCO SERFINANZA
> > * BANCO SUDAMERIS
> > * BANCO UNION
> > * BANCO W
> > * BANCOLOMBIA
> > * BANCOOMEVA
> > * BBVA COLOMBIA
> > * BENEFICIAR
> > * BIENESTAR
> > * BOLD
>
> > [tab] C
> >
> > * CARDIOCOOP
> > * CAVIPETROL
> > * CESCA
> > * CFA
> > * CIDESA
> > * COAPAZ
> > * COASMEDAS
> > * COBELÉN
> > * CODEMA
> > * COEDUCADORES BOYACA
> > * COESCOOP
> > * COFACENEIVA
> > * COFINAL
> > * COINPROGUA
> > * COLTEFINANCIERA
> > * COMEDAL
> > * COMERCIACOOP
> > * COMULSEB
> > * COMULTRASAN
> > * COMUNA
> > * CONEXRED
> > * CONFIAMOS
> > * CONFIAR
> > * CONGENTE
> > * COOABEJORRAL
> > * COOACUEDUCTO
> > * COOBAGRE
> > * COOCREAFAM
> > * COODIN
> > * COOEDUCAR
> > * COOFINANCIAR
> > * COOFIPOPULAR
> > * COOFISAM
> > * COOFRASA
> > * COOGOMEZPLATA
> > * COOGRANADA
> > * COOINDEGABO
> > * COOINPE
> > * COOMBEL
> > * COOMEC
> > * COOMPARTIR
> > * COOMSERVI
> > * COOMULDESA
> > * COOMULTAGRO
> > * COOMULTRAISS
> > * COONECTA
> > * COONFIE
> > * COOPACREDITO SANTA ROSA
> > * COOPANTEX
> > * COOPARAMO
> > * COOPCANAPRO
> > * COOPCARVAJAL
> > * COOPCENTRAL
> > * COOPEAIPE
> > * COOPEBIS
> > * COOPECREDITO ENTRERRIOS
> > * COOPEMSURA
> > * COOPEMTOL
> > * COOPERATIVA ALIANZA
> > * COOPERATIVA AVANZA
> > * COOPERATIVA AVP
> > * COOPERATIVA CUB
> > * COOPEREN
> > * COOPERENKA
> > * COOPETEXAS
> > * COOPETROL
> > * COOPICREDITO
> > * COOPIGON
> > * COOPINTEGRATE
> > * COOPIO XII
> > * COOPJUDICIAL
> > * COOPLAROSA
> > * COOPMACEO
> > * COOPRIACHON
> > * COOPROCAL
> > * COOPROFESIONALES
> > * COOPROFESORES
> > * COOPROFESORESUN
> > * COOPRUDEA
> > * COOPSANFRANCISCO
> > * COOPSANSIMON
> > * COOPSERVIVÉLEZ
> > * COOPSOCIAL
> > * COOPSUYA
> > * COOPTENJO
> > * COOPTRAISS
> > * COOPVALLE
> > * COOPYARUMAL
> > * COOSANANDRESITO
> > * COOSANLUIS
> > * COOSANROQUE
> > * COOSERVUNAL
> > * COOSVICENTE
> > * COOTEP
> > * COOTRACERREJON
> > * COOTRACHEC
> > * COOTRADECUN
> > * COOTRAIPI
> > * COOTRAMED
> > * COOTRAPELDAR
> > * COOTRASENA
> > * COOTRAUNION
> > * COOTREGUA
> > * COOVITEL
> > * COPACREDITO
> > * COPROCENVA
> > * COPVILLANUEVA
> > * CORPECOL
> > * COTRAFA
> > * COTRASENA
> > * COVICSS
> > * COY-AMOR
> > * CREARCOOP
> > * CRECIAT
> > * CREDIFLORES
> > * CREDIFUTURO
> > * CREDISERVIR
> > * CREZCAMOS
>
> > [tab] D
> >
> > * DALE
> > * DAVIBANK
> > * DAVIPLATA
>
> > [tab] F
> >
> > * FAVI UTP
> > * FEBOR
> > * FECEL
> > * FECSA
> > * FEDANE
> > * FEDEJOHNSON
> > * FEDIAN
> > * FEG
> > * FELAFRANCOL
> > * FEMPHA
> > * FEPIMSA
> > * FESICOL
> > * FETRABUV
> > * FEU QUINDIO
> > * FINANCIERA COAGROSUR
> > * FINANCIERA COFINCAFE
> > * FINCOMERCIO
> > * FINECOOP
> > * FODELSA
> > * FODUN
> > * FONALIANZA
> > * FONCALDAS
> > * FONDECOM
> > * FONDECOR
> > * FONDUCAR
> > * FONEDH
> > * FONFABRICAFE
> > * FONRECAR
> > * FONVALLE
> > * FORJAR
> > * FOTRANORTE
>
> > [tab] G
> >
> > * GRANCOOP
>
> > [tab] J
> >
> > * JFK
> > * JURISCOOP
>
> > [tab] K
> >
> > * KAMIN
>
> > [tab] L
> >
> > * LULO BANK
>
> > [tab] M
> >
> > * MANUELITACOOP
> > * MICROEMPRESAS DE COLOMBIA
> > * MONO COLOMBIA
> > * MOVII
> > * MULTIACOOP
> > * MULTICOOP
> > * MUTUAL CANAPRO
> > * MUTUAL INTEGRAL
> > * MUTUAL SAN JERONIMO
>
> > [tab] N
> >
> > * NEQUI
> > * NU COLOMBIA
>
> > [tab] P
> >
> > * PAYU
> > * PEXTO
> > * POWWI
> > * PRESENTE
> > * PREVENSERVICIOS
> > * PROMEDICO
> > * PROSPERANDO
>
> > [tab] R
> >
> > * RAPPIPAY
>
> > [tab] S
> >
> > * SERVICONAL
> > * SERVIMCOOP
> > * SERVITRUST
> > * SUCREDITO
>
> > [tab] T
> >
> > * TAX LA FERIA
> > * TECNIPAGOS
> > * TELEPOSTAL
>
> > [tab] U
> >
> > * UALÁ
> > * UTRAHUILCA
>
> > [tab] V
> >
> > * VIDASOL

***

## 常见问题

> [accordion] 我的 Bre-B 虚拟账户需要多久才能激活？
>
> 哥伦比亚虚拟账户通常会在 **6 秒**内激活。创建虚拟账户（VA）的响应会返回 `status.code: "100" INPROGRESS`。请轮询获取虚拟账户状态 endpoint，直到收到 `status.code: "200" COMPLETED`，再将密钥分享给付款方。

> [accordion] 我可以使用同一个 Bre-B 密钥进行多次支付吗？
>
> 是的。虚拟账户及其关联的 Bre-B 密钥将一直保持激活状态，直到您明确[停用或删除](https://docs.localpayment.com/zh/docs/activate-deactivate-virtual-account.md)它们。您可以无限次地使用同一密钥接收付款。

> [accordion] 如果付款人支付的金额超过最高限额会发生什么情况？
>
> 超过最高限额（收款为 12,110,000 哥伦比亚比索，付款为 11,552,000 哥伦比亚比索）的转账将被 Bre-B 网络拒绝。付款人将在其银行应用程序中看到错误提示。对于大额转账，请将其拆分为多笔交易。

> [accordion] 我可以在营业时间以外接收 Bre-B 付款吗？
>
> 可以——根据 Banco de la República 的规定，Bre-B 全天候 24/7/365 运行。没有停机窗口，没有周末限制，也没有节假日限制。

> [accordion] account.number 和 account.alias 有什么区别？
>
> 这些字段根据数据流的不同而发挥不同的作用：
>
> * **`beneficiary.bank.account.number`**：用于获取虚拟账户状态的**响应**——Localpayment 在此返回为您的收款虚拟账户自动生成的 Bre-B 密钥。这是只读的输出字段。
> * **`beneficiary.bank.account.alias`**：用于创建付款的**请求**——发起付款时，您在此提供收款方的 Bre-B 密钥。这是输入字段。
>
> 对于付款，切勿包含 `account.type` 或 `account.number`——仅使用 `account.alias`。

> [accordion] 为什么我的付款请求会被拒绝，并提示 'Invalid param + \[paymentMethod.code]'？
>
> 此错误通常表示 `paymentMethod.code` 不是 `"0062"`，或 `paymentMethod.type` 不是 `"BankTransfer"`。请仔细检查这两个字段，并确保 `paymentMethod.flow` 设置为 `"DIRECT"`。同时请确认请求体以 JSON **数组**（用 `[...]` 包裹）的形式传递。

> [accordion] Localpayment 如何为我的虚拟账户生成 Bre-B 密钥？
>
> 密钥是根据您在创建 VA 账户时提供的受益人姓名确定性地生成的：
>
> 1. 从受益人姓名中删除所有空格和特殊字符。
> 2. 取结果字符串的前 10 个字母数字字符。
> 3. 组合：`@` + `LP` + 姓名片段 + 4 位顺序计数器。
>
> 示例：`"TechColombia SAS"` → 去除空格 → `TechColombiaSAS` → 前 10 位 → `TechColomb` → 密钥 = `@LPTechColomb0001`。
>
> 计数器（`0001`、`0002` 等）会随每个签发的密钥递增。最终密钥长度为 10 到 16 个字母数字字符，不含 `@` 符号。

***

## 测试您的集成

### 沙盒环境

所有测试均应在预发布环境中进行：

```
# Virtual Account (payin)
POST https://api.stage.localpayment.com/api/virtual-account

# Bank Transfer payout
POST https://api.stage.localpayment.com/api/payout/
```

### 测试场景

请确认您的集成方案能够处理以下场景：

1. **VA 创建**：为哥伦比亚创建虚拟账户，并确认返回 `100 INPROGRESS` 响应。
2. **密钥获取**：轮询状态 endpoint 直到 `status.code: "200"`，然后验证 `beneficiary.bank.account.number` 包含有效的 Bre-B 密钥。
3. **收款接收（Payin）**：模拟一笔入账的 Bre-B 付款，并验证您的 webhook 处理程序返回 `HTTP 200`。有关 webhook 设置，请参阅[接收付款通知](https://docs.localpayment.com/zh/docs/receive-payment-notifications.md)。
4. **付款提交（Payout）**：使用代码 `0062` 和有效的 `beneficiary.bank.account.alias` 提交付款。
5. **重复通知处理**：验证您的系统使用 `internalId` 或 `externalId` 以幂等方式处理 webhook 重试。
6. **账户生命周期**：测试[启用、禁用](https://docs.localpayment.com/zh/docs/activate-deactivate-virtual-account.md)和[删除](https://docs.localpayment.com/zh/docs/delete-virtual-account.md)虚拟账户。

***

## 后续步骤

> [card] [管理虚拟账户生命周期](https://docs.localpayment.com/zh/docs/activate-deactivate-virtual-account.md)
>
> 启用或禁用 Bre-B 密钥，即可暂时暂停或恢复收款，而无需删除虚拟账户。

> [card] [退还收款](https://docs.localpayment.com/zh/docs/refund-virtual-account-payment.md)
>
> 通过 Localpayment API 或 Business Portal 对收到的 Bre-B 付款进行退款。

> [card] [付款说明](https://docs.localpayment.com/zh/docs/payment-instructions.md)
>
> 了解您需要向付款人提供哪些关于哥伦比亚虚拟账户付款的信息。

> [card] [查看交易详情](https://docs.localpayment.com/zh/reference/get-transaction-status.md)
>
> 使用 Localpayment API 获取完整的交易信息，以便进行审计和对账。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.