跳转到主要内容
了解如何使用 Localpayment Webhook,以便接收每次付款事件的实时通知。本指南将帮助您验证签名、处理 Webhook 数据并保持集成同步。 我们使用 Webhook 来通知您的应用程序有关您帐户中发生的事件。它们对于异步更新尤其有用,例如付款确认、付款处理完成或订阅状态更改时。

概述

Webhook 可实时通知您 Localpayment 账户中的交易状态变更和其他重要事件。您无需轮询我们的 API 获取状态更新,只需配置 Webhook endpoint,即可在事件发生时立即接收通知。

实时更新

交易状态变更时立即接收通知

多种事件

支持 payin、payout、虚拟账户、订阅等

安全投递

HMAC 签名验证确保 Webhook 的真实性

Webhook 的工作原理

  1. 事件发生:Localpayment 系统中的交易状态发生变化
  2. 发送 Webhook:Localpayment 向您的 Webhook endpoint 发送 JSON 有效负载。
  3. 签名验证:您的 endpoint 使用 x-Signature 标头验证请求。
  4. 返回 200 OK:您的 endpoint 返回 200 OK 响应
  5. 处理事件:您的应用程序异步处理 webhook 数据
传出的 Webhook 请求中的 Content-Type 标头为 text/plain; charset=utf-8,而不是 application/json。请求体仍然是有效的 JSON 有效负载。无论 Content-Type 标头的值是什么,都请将其作为 JSON 解析。

先决条件

设置 Webhook 之前,请确保您已具备以下条件:

账户设置

为您的目标国家/地区正确设置账户并进行业务验证。

密钥

您在 Localpayment Business Portal 上的 webhook 密钥。

配置

Business Portal 搭建

  1. 在您的 Localpayment Business Portal 中,导航至 “配置”→“客户端”。
  2. 选择要配置的客户端。
  3. 点击**“通知”**选项卡,然后选择要配置的 webhook 类型。
  4. 点击**“添加”**按钮,然后输入以下信息:

安全与认证

Localpayment 使用 HMAC 签名对所有 webhook 请求进行签名,以验证其真实性。

签名验证

每个 Webhook 请求都包含一个 x-Signature 标头。其值的格式为算法名称,后跟一个空格和十六进制编码的 HMAC-SHA256 签名:
要验证签名,请使用您的 Webhook 密钥计算原始请求体的 HMAC-SHA256 哈希值,然后将其与请求头中的哈希部分进行比较——即 HMAC-SHA256 之后的部分。
在比较之前,请先从标头值中去掉 HMAC-SHA256 前缀。将完整的标头字符串与计算出的哈希值进行比较将始终失败。

示例实现


Webhook有效载荷

所有 Webhook 有效负载都共享一个通用结构,其中特定于事件的数据位于 data 对象中。这种一致的格式使您更容易解析和处理不同事件类型的 Webhook。

常见的 Webhook 结构

无论事件类型如何,以下字段始终存在于每个 webhook 有效负载中:
transactionType 按设计出现两次。 根级别字段充当您的 Webhook 处理程序的路由键。该字段在 data 对象中重复出现,以使每个有效负载自成一体,便于单独存储或转发事件。两个值始终相同。
fxSource 类型。 fxSource 字段始终是浮点数。它表示用于计算手续费或税费的汇率。当不适用外汇转换时(相同币种的交易),该值为 0 或 0.0。

Payin 事件

银行卡支付(信用卡/借记卡)

Approved
Chargeback
Completed
Refunded
Rejected

银行转账主账户

订阅


支付事件


虚拟账户事件

创建虚拟账户

虚拟账户创建成功后,Localpayment 将向您配置的回调 URL 发送一个 POST 请求。此通知确认账户信息已激活,可以接收付款。

已收到付款(Payin)

每当客户完成向虚拟账户的付款时,Localpayment 都会向您注册的 endpoint 发送 webhook 通知。所有付款通知都遵循相同的结构并包含相同的信息——无论付款时间或金额如何。这些信息包括金额、币种、状态和交易参考号等关键字段,方便您自动进行对账并相应地更新内部系统。

货币兑换事件

以下字段仅适用于货币兑换 webhook 事件:
Completed

结算事件

Wire In

Completed

Wire Out

Completed

Wire Out(加密货币)

当 Wire Out 以受支持的加密货币(例如 USDT 或 USDC)支付时,完成回调还会包含一个 hash 字段,其中是区块链交易哈希,以便您在区块浏览器中独立验证该付款。法币 Wire Out 的负载中不包含此字段。
Completed (crypto)

字段参考

了解 webhook 有效负载中的详细字段对于正确的对账和结算至关重要。
最后修改于 2026年11月19日