Webhook 通知

本文档介绍了如何接收和处理来自 Codapay 的服务器间 Webhook 通知。这些通知可确保您的后端与用户在支付流程中的交易状态保持同步。

概述

Codapay 使用 webhook 在交易达到最终状态或关键里程碑时通知您的“完成通知 URL”。

请确保已在发布商门户中配置“完整通知 URL”。有关详细说明，请参阅“设置付款”指南。

事件类型

对于 Codapay 集成，您的端点应准备好处理以下eventType值：

事件类型	类型	Description
PAYMENT_METHOD_ADDED	​Payment Method notification​	购物者成功保存了一种新的支付方式。
PAYMENT_METHOD_REMOVED	​Payment Method notification​	购物者删除了已保存的付款方式。

通知有效载荷结构

通知以请求的形式发送，POST请求体为 JSON 格式。每种类型的通知都有其特定的结构和内容。

付款方式通知

Field	类型	介绍
eventType	string	所报告的具体事件类型（例如，PAYMENT_METHOD_ADDED）
timestamp	string	事件发生的时间戳
shopper	object	包含购物者详细信息的对象，例如 ID、电子邮件或合作伙伴特定标识符。
paymentMethod	object	有关所用支付工具的信息（例如，令牌、卡类型、后四位数字）。

PAYMENT_METHOD_ADDED

当新卡成功保存并关联到购物者个人资料时，系统会发送此通知。

通知有效载荷

{
  "eventType": "PAYMENT_METHOD_ADDED",
  "timestamp": "2025-06-19T02:48:39.568907Z",
  "shopper": {
    "id": "shp_sg197861636b40021",
    "partner_shopper_id": "test_partner_123_Id",
    "email": "[e-mail]"
  },
  "paymentMethod": {
    "id": "pmt_sg1978616a1900024",
    "type": "card",
    "card": {
      "lastFour": "7263",
      "expirationMonth": "04",
      "expirationYear": "2027"
    }
  }
}

回复通知

为确认收到通知，您的服务器必须响应一个包含200 OK以下 JSON 正文的响应：

{
  "ResultCode": 0
}

重试策略：如果未收到有效响应，Codapay 将每隔 5 分钟重新发送一次通知，共发送 3 次。如果所有尝试均失败，系统将向您的技术联系人发送电子邮件提醒。