概述
Bre-B 与 PSE:何时使用哪种?
哥伦比亚已将 PSE 作为成熟的 A2A 支付方式。Bre-B 并非取代 PSE,而是提供了一种更快、更便捷的替代方案。请使用下表选择适合您使用场景的支付方式:Bre-B 密钥(Llave)
llave(密钥)是一个简短的字母数字别名,用于代替 Bre-B 转账中的完整银行账号。付款人只需在银行应用程序中输入密钥即可,无需提供完整的账户信息。 Localpayment 如何生成您的密钥 当您为哥伦比亚创建虚拟账户时,Localpayment 会自动生成一个字母数字密钥——您无需选择或配置密钥类型。该密钥会根据您提供的收款人姓名自动生成:
密钥总长度:10 到 16 个字母数字字符(不含
@ 前缀符号)。
示例——受益人姓名为 "TechColombia SAS":
- 去除空格和特殊字符 →
TechColombiaSAS - 取前 10 个字母数字字符 →
TechColomb - 组合 →
@+LP+TechColomb+0001=@LPTechColomb0001(16 个字符)
status.code: "200"),生成的密钥会在 beneficiary.bank.account.number 中返回。
限制与可用性
演示
看看付款方在实际操作中如何使用 Bre-B 虚拟账户:接收 Bre-B 付款(Payin)
通过 Bre-B 收款(Payin)使用 虚拟账户 基础设施。Localpayment 会为您创建的每个账户生成一个唯一的 Bre-B 字母数字密钥。付款人可以通过任何支持 Bre-B 的银行应用程序向该密钥汇款。结算即时完成,并且完全自动化。工作原理
- 创建虚拟账户:您的系统使用受益人详细信息调用创建虚拟账户 endpoint。
- 获取 Bre-B 密钥:账户激活后(约 6 秒),查询其状态,从
beneficiary.bank.account.number获取系统生成的密钥。 - 将密钥分享给付款人:付款人在其银行应用程序中输入密钥以发起转账。
- 接收资金和 webhook:Localpayment 接收转账并向您配置的 endpoint 发送实时 webhook。
开始之前
请确保您已备好:第一步:创建虚拟账户
向创建虚拟账户endpoint 发送POST 请求。
关键请求参数
请参阅 API 参考,了解所有可用参数。
示例请求
curl
成功响应
错误响应
激活时间:哥伦比亚虚拟账户通常会在 6 秒内激活。轮询状态 endpoint 或稍等片刻后再检索 Bre-B 密钥。
非本地受益人如果您的收款人是外国居民(非哥伦比亚本地居民),则虚拟账户必须以账户持有人的身份在 Localpayment 注册。这既能确保符合当地银行法规,又能让您代表外国实体接收付款。
步骤 2:获取您的 Bre-B 密钥
虚拟账户激活后(status.code: "200"),向获取虚拟账户状态endpoint 发送 GET 请求。
示例请求
curl
成功响应
关键响应字段
将
beneficiary.bank.account.number 的值分享给付款方。无需提供其他银行账户信息。
步骤 3:付款方发起转账
付款方在任何参与的哥伦比亚银行应用程序或数字钱包中使用 Bre-B 密钥:- 打开银行应用程序,选择 Bre-B 或按密钥转账选项。
- 输入 Bre-B 密钥(例如
@LPTechColomb0001)作为收款目标。 - 输入金额并确认转账。
- 支付将在 20 秒内完成。
第四步:处理 Webhook
付款入账后,Localpayment 会向您配置的 endpoint 发送POST 请求。您的服务器必须返回 HTTP 200 OK 以确认接收。有关设置说明,请参阅 Webhooks 指南。
Webhook 载荷示例
关键 Webhook 字段
第五步:跟踪收款状态
Webhooks(推荐)
款项到账后即可收到实时通知。在生产环境中最为高效。
状态 API endpoint
通过编程方式查询交易状态。可用于核对错过的 webhook 通知。
Business Portal 视图
用于监控交易的可视化界面。非常适合人工监督和详细分析。
完整参考请在我们的交易状态文档中查看所有状态码。
发送 Bre-B 付款(Payout)
要向收款方的 Bre-B 密钥发送资金,请使用 银行转账付款 流程,支付方式代码为0062。收款方必须已在其银行注册 Bre-B 密钥。您需通过 beneficiary.bank.account.alias 提供该密钥。
工作原理
- 收集收款方的 Bre-B 密钥:获取收款方已注册的 llave(任何支持的密钥类型:字母数字、电话号码、电子邮件、证件或商户代码)。
- 提交付款:使用代码
0062调用创建付款 endpoint,并在beneficiary.bank.account.alias中传入密钥。 - 跟踪转账:通过 Webhook 或状态 API 监控状态,直至
200 Completed。
第一步:发起付款
向创建付款endpoint 发送POST 请求。请注意,请求体是一个数组。
关键请求参数
示例请求
curl
成功响应
错误响应
步骤 2. 跟踪付款状态
Webhooks(推荐)
转账扣款时接收实时通知。最适用于生产环境。
状态 API endpoint
通过编程方式查询付款状态。这对于对账和异常处理非常有用。
Business Portal 视图
用于监控和手动批准付款的可视化界面。
完整参考请在我们的交易状态文档中查看所有状态码。
支持的银行
Bre-B 付款可以在所有参与的哥伦比亚金融机构之间发送和接收——200 多家银行、数字钱包和与哥伦比亚共和国银行网络连接的合作社。常见问题
我的 Bre-B 虚拟账户需要多久才能激活?
我的 Bre-B 虚拟账户需要多久才能激活?
哥伦比亚虚拟账户通常会在 6 秒内激活。创建虚拟账户(VA)的响应会返回
status.code: "100" INPROGRESS。请轮询获取虚拟账户状态 endpoint,直到收到 status.code: "200" COMPLETED,再将密钥分享给付款方。我可以使用同一个 Bre-B 密钥进行多次支付吗?
我可以使用同一个 Bre-B 密钥进行多次支付吗?
是的。虚拟账户及其关联的 Bre-B 密钥将一直保持激活状态,直到您明确停用或删除它们。您可以无限次地使用同一密钥接收付款。
如果付款人支付的金额超过最高限额会发生什么情况?
如果付款人支付的金额超过最高限额会发生什么情况?
超过最高限额(收款为 12,110,000 哥伦比亚比索,付款为 11,552,000 哥伦比亚比索)的转账将被 Bre-B 网络拒绝。付款人将在其银行应用程序中看到错误提示。对于大额转账,请将其拆分为多笔交易。
我可以在营业时间以外接收 Bre-B 付款吗?
我可以在营业时间以外接收 Bre-B 付款吗?
可以——根据 Banco de la República 的规定,Bre-B 全天候 24/7/365 运行。没有停机窗口,没有周末限制,也没有节假日限制。
account.number 和 account.alias 有什么区别?
account.number 和 account.alias 有什么区别?
这些字段根据数据流的不同而发挥不同的作用:
beneficiary.bank.account.number:用于获取虚拟账户状态的响应——Localpayment 在此返回为您的收款虚拟账户自动生成的 Bre-B 密钥。这是只读的输出字段。beneficiary.bank.account.alias:用于创建付款的请求——发起付款时,您在此提供收款方的 Bre-B 密钥。这是输入字段。
account.type 或 account.number——仅使用 account.alias。为什么我的付款请求会被拒绝,并提示 'Invalid param + [paymentMethod.code]'?
为什么我的付款请求会被拒绝,并提示 'Invalid param + [paymentMethod.code]'?
此错误通常表示
paymentMethod.code 不是 "0062",或 paymentMethod.type 不是 "BankTransfer"。请仔细检查这两个字段,并确保 paymentMethod.flow 设置为 "DIRECT"。同时请确认请求体以 JSON 数组(用 [...] 包裹)的形式传递。Localpayment 如何为我的虚拟账户生成 Bre-B 密钥?
Localpayment 如何为我的虚拟账户生成 Bre-B 密钥?
密钥是根据您在创建 VA 账户时提供的受益人姓名确定性地生成的:
- 从受益人姓名中删除所有空格和特殊字符。
- 取结果字符串的前 10 个字母数字字符。
- 组合:
@+LP+ 姓名片段 + 4 位顺序计数器。
"TechColombia SAS" → 去除空格 → TechColombiaSAS → 前 10 位 → TechColomb → 密钥 = @LPTechColomb0001。计数器(0001、0002 等)会随每个签发的密钥递增。最终密钥长度为 10 到 16 个字母数字字符,不含 @ 符号。测试您的集成
沙盒环境
所有测试均应在预发布环境中进行:测试场景
请确认您的集成方案能够处理以下场景:- VA 创建:为哥伦比亚创建虚拟账户,并确认返回
100 INPROGRESS响应。 - 密钥获取:轮询状态 endpoint 直到
status.code: "200",然后验证beneficiary.bank.account.number包含有效的 Bre-B 密钥。 - 收款接收(Payin):模拟一笔入账的 Bre-B 付款,并验证您的 webhook 处理程序返回
HTTP 200。有关 webhook 设置,请参阅接收付款通知。 - 付款提交(Payout):使用代码
0062和有效的beneficiary.bank.account.alias提交付款。 - 重复通知处理:验证您的系统使用
internalId或externalId以幂等方式处理 webhook 重试。 - 账户生命周期:测试启用、禁用和删除虚拟账户。
后续步骤
管理虚拟账户生命周期
启用或禁用 Bre-B 密钥,即可暂时暂停或恢复收款,而无需删除虚拟账户。
退还收款
通过 Localpayment API 或 Business Portal 对收到的 Bre-B 付款进行退款。
付款说明
了解您需要向付款人提供哪些关于哥伦比亚虚拟账户付款的信息。
查看交易详情
使用 Localpayment API 获取完整的交易信息,以便进行审计和对账。

