跳转到主要内容
每次虚拟账户收到付款时,您都会收到即时 Webhook 通知,从而自动更新您的系统并确认到账。 一旦您创建了虚拟账户并将其映射到内部系统中的特定客户或发票,每当该账户成功收到付款时,Localpayment 都会自动向您的服务器发送 Webhook 通知。 重要提示:虚拟账户用作专用的付款目的地。您可自行管理其内部归属信息,但该账号本身可接收任何付款人的款项。付款通知将包含实际付款人的详细信息,方便您将付款与内部客户映射进行核对。 这些实时通知使您能够自动确认到账、更新余额并核对付款,而无需人工验证。

开始之前

请确保您已具备以下条件:
  • 已通过创建虚拟账户endpoint 成功创建虚拟账户。
  • 在您的商户账户中配置了通知 endpoint(Webhook URL)。
  • 能够接收来自 Localpayment 服务器的 HTTPS POST 请求。
  • 后端具备安全地验证和解析 Webhook 有效载荷的逻辑。

工作原理

  1. 付款人向您的系统先前生成的虚拟账户号码发送转账。
  2. 资金到账并经 Localpayment 验证后,系统会向您配置的 Webhook endpoint 发送 PayIn 通知。
  3. 您的系统必须以 200 OK 响应确认该通知。
  4. 然后,您可以更新内部记录,将虚拟账户标记为已付款,或将相应的订单标记为已完成。

如果您的服务器没有响应 HTTP 200,Localpayment 将使用指数退避重试来保证送达。

示例通知(Webhook 有效载荷)

以下是成功支付到虚拟账户的示例有效载荷:

用于匹配的 Webhook 字段

Webhook 通知包含用作标识符的特定字段。请使用下表将收到的付款与您的内部记录进行匹配。

使用付款参考

付款人可以在转账时添加参考信息(例如订单号)。此数据会显示在 Webhook 的 tracking 对象中,用于直接匹配。

重要提示
  • 可用性: tracking 对象仅在 Webhook 中可用,在交易报告或 API 中不可用。
  • 对于墨西哥(SPID),externalId 对应于墨西哥银行(Banco de México)的跟踪码(Clave de Rastreo),使其成为对账的权威字段。

跟踪对象示例


通知中的关键标识符

该通知包含由不同方生成的多个参考字段和跟踪字段。了解每个字段的来源和可靠性有助于您构建可靠的对账策略。

referenceCode

由 Localpayment 生成。在每个国家/地区和每个支付渠道中,它始终遵循 XXXX-XXXX-XXXX 格式(三个四字符字母数字块),这可以确认通知源自 Localpayment。 referenceCode 是供人工阅读的 Localpayment 参考编号,而不是幂等键。如需去重和幂等性,请使用 internalId 或 externalId。

tracking.id

由支付渠道或付款人银行生成,而非由 Localpayment 生成。格式因国家/地区而异: 请勿将 tracking.id 视为在所有支付渠道中都具有全局唯一性。对于哥伦比亚 Bre-B,请将其用作支付渠道侧的主要标识符;对于其他国家/地区,请将其作为辅助参考。

tracking.reference

同样由支付渠道或银行生成。其内容和可用性各不相同:
  • 阿根廷、智利、哥伦比亚:与 tracking.id 相同。
  • 墨西哥(SPEI/TEF):付款人在转账时输入的较短的银行参考号。
  • 秘鲁:可能为空,或包含 "NO REF"。
请勿依赖 tracking.reference 作为有保证的或唯一的标识符。

tracking.concept

用于记录付款说明。但实际上,该字段通常包含系统生成的字符串或占位符字符串,而不是付款人自由填写的文本: 请勿将 tracking.concept 用作关键字段,也不要假定其包含付款人输入的自由文本。仅将其视为补充信息。

特定国家/地区

使用虚拟账户时,您必须考虑一些重要的国家/地区特定细节。这些细节会影响付款通知的处理方式以及交易对账方式。以下是某些市场已知差异的概述:
国家/付款方式Webhook 注意事项
哥斯达黎加(SINPE)
  • tracking.concept 字段包含付款人在转账时输入的描述。此值可能会被发起银行截断,因此您可能会看到末尾的下划线(例如 "Steph_test_____")。
哥伦比亚(Bre-B)
  • 对于 Bre-B 虚拟账户收款,paymentMethod.code 始终为 "2006"。
  • payer.bank.account.type 始终为 "BREB" — 确认付款人通过 Bre-B 网络发送了资金。
  • beneficiary.bank.account.type 始终为 "KEY" — 即分配给您的虚拟账户的接收 Bre-B 密钥。
  • Bre-B 实时结算:唯一的收款状态是 "200" COMPLETED。没有中间状态。
  • tracking.id 和 tracking.reference 包含 Bre-B 网络交易 ID — 请将这些 ID 作为对账的权威参考。
  • tracking.concept 可能包含付款人输入的描述,但通常包含系统生成的字符串(例如 "Transfer via BRE-B")。请勿将其视为付款人输入的自由文本。
墨西哥(SPID)
  • SPID 转账仅限公司付款人使用。
  • externalId 字段对应于墨西哥银行(Banco de México)分配的跟踪码(Clave de Rastreo)。
  • 请使用 externalId 作为对账的权威参考。
秘鲁

无法提供付款人全名的金融机构

  • 秘鲁:部分秘鲁金融机构在交易详情中不提供付款人的全名。由于这些机构发送的结算数据中缺少此信息,您可能无法正确识别付款人。
  • 007 – CITIBANK DEL PERU S.A.
  • 056 – BANCO SANTANDER PERU S.A.
  • 805 – CAJA MUNICIPAL DE AHORRO Y CRÉDITO SULLANA
  • 813 – CAJA MUNICIPAL DE AHORRO Y CRÉDITO TACNA

处理通知

您的服务器必须按如下方式处理每条通知:
  1. 验证请求签名。
  2. 验证 internalId 或 externalId,以确保幂等性;切勿对同一通知处理两次。
  3. 更新您的系统,将相应的发票、钱包或订单标记为已付款。
  4. 返回 HTTP 200 OK 以确认收到。

确认收到通知

只有当您的服务器响应以下内容时,Localpayment 才认为 Webhook 已成功送达:
如果未收到确认,Localpayment 将以逐渐增加的间隔重试通知数次。
最后修改于 2026年11月10日