跳到正文
PayHub开发者文档

查询事件

契约 v1.0.0

getEvent
GET/v1/events/{event_id}
所需权限

所需权限按事件所属业务校验，缺少对应权限返回 403：

payment.*payments:read
dispute.*payments:read
refund.*refunds:read
settlement.*finance:read

获取当前商户、当前环境的事件，用于补齐遗漏的 Webhook 或核对载荷。载荷与投递时相同，事件 ID 不变。 所需权限取决于事件所属业务：payment.* 与 dispute.* 需要 payments:read，refund.* 需要 refunds:read，settlement.* 需要 finance:read；缺少对应权限返回 403。 事件不会自动清除，历史事件都可查询；不属于当前商户环境的事件返回 404，商户后台"发送测试事件"产生的测试事件不是业务事件，同样返回 404。

请求头

请求头必填格式说明
Authorization是Bearer <API_KEY>

服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。

请求示例

curl
curl -X GET 'https://api.payhub.bbpays.site/v1/events/<EVENT_ID>' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>'

需要替换的占位符

  • <EVENT_ID>：事件 ID（evt_ 开头），见 Webhook 请求头 X-Pay-Event-Id
  • <TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建

说明

服务端 API Key 只能在你的服务端使用，文档站不提供在线调试。获取测试 Key：商户后台 API Key（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）

响应

事件。

payment.succeeded 事件（与投递时的载荷一致）
{
  "id": "evt_demo_001",
  "type": "payment.succeeded",
  "api_version": "v1",
  "created_at": "2026-09-23T09:05:00Z",
  "environment": "test",
  "merchant_id": "mer_demo_001",
  "data": {
    "object": {
      "id": "pay_demo_001",
      "merchant_order_no": "ORDER-DEMO-001",
      "amount": 10000,
      "currency": "USD",
      "status": "succeeded",
      "latest_attempt_id": "pat_demo_001",
      "version": 4
    }
  },
  "request_id": "req_demo_036"
}

响应字段

返回对象 字段说明见 对象小节。

名称类型必填说明
id
string必填

事件 ID，用于去重。

示例：evt_demo_001

type
string必填

事件类型，取值见 webhooks.v1.yaml 的 EventType；客户端须容忍未知类型。

示例：payment.succeeded

api_version
string必填

载荷的 API 版本。

示例：v1

created_at
string(date-time)必填

事件创建时间；不能代替签名时间。

示例：2026-09-23T09:05:00Z

environment
string必填

环境：test 为测试，live 为生产。测试与生产对象相互隔离。

  • test
  • live
  • 将来可能新增取值；不认识的状态不要当作成功。

示例：test

merchant_id
string必填

商户号。

示例：mer_demo_001

data
EventData必填
object
object必填

事件发生时的业务对象快照（Payment、Refund、Dispute 或 Settlement），只含商户有权查看的最小必要数据，含 id 与 version。

示例：{"id":"pay_demo_001","merchant_order_no":"ORDER-DEMO-001","amount":10000,"currency":"USD","status":"succeeded","latest_attempt_id":"pat_demo_001","version":4}

request_id
string必填

本次请求的唯一标识，用于排查与支持。

示例：req_demo_001

可能的错误码

HTTP错误码何时出现如何处理
404not_foundID 错误；用测试 Key 查询生产对象；查询平台异常退款（不通过开放 API 返回）核对 ID 与 Key 的环境；平台不会透露对象是否属于其他商户
403forbidden只读 Key 创建退款；getEvent 缺少事件所属业务的读权限；请求来源 IP 不在 Key 的白名单时返回更具体的 ip_not_allowed使用具备所需 scope 的 Key；不要绕过限制
401unauthenticated通用未带 Authorization；Key 复制不完整；轮换后旧 Key 已过期；Key 被撤销检查凭据，在 商户后台 API Key 页面 核对 Key 状态与环境
429rate_limited通用商户、Key 维度的频率限制；换 Key 不能绕过商户总限额等待 Retry-After 秒后用原幂等键重试
500internal_error通用—用原幂等键重试或按商户订单号 / 退款号查询；不能换键重扣
502 / 503upstream_unavailable通用上游或平台依赖故障，平台无法确认本次请求是否已生效同上

注意事项

  • 返回的事件载荷与投递时一致、事件 ID 不变，用于补齐遗漏的 Webhook，见事件类型。
  • 事件不会自动清除，历史事件都可以查询。
  • 所需权限按事件所属业务校验（dispute.* 需要 payments:read），缺少对应权限返回 403；不属于当前商户环境的事件返回 404。
  • 开放 API 不提供争议资源：争议通过 dispute.* 事件、本接口与商户后台查看。
这页有帮助吗？