> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/xun-huan-fu-kuan-ji-jiang-tui-chu/webhook-tong-zhi.md).

# Webhook 通知

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

### 概述 <a href="#overview" id="overview"></a>

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

{% hint style="info" %}
请确保已在发布商门户中配置“完整通知 URL”。有关详细说明，请参阅[“设置付款”指南。](https://coda-payments.gitbook.io/coda-public-technical-documentation/codapay/getting-started/set-up-payments)
{% endhint %}

### 事件类型 <a href="#event-types" id="event-types"></a>

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

| 事件类型                     | 类型                                                                                                                                                                                                                                           | Description                                                             |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `PAYMENT_METHOD_ADDED`   | ​[Payment Method notification](https://app.gitbook.com/o/6r6nr9F9QL33fFAul7Gs/sites/site_QaGAx/s/l56STCN5yoV1K1MhVEvU/~/diff/~/revisions/current/codapay/recurring-payments-coming-soon/webhook-notifications#payment-method-notifications)​ | 购物者成功保存了一种新的支付方式。                                                       |
| `PAYMENT_METHOD_REMOVED` | ​[Payment Method notification](https://app.gitbook.com/o/6r6nr9F9QL33fFAul7Gs/sites/site_QaGAx/s/l56STCN5yoV1K1MhVEvU/~/diff/~/revisions/current/codapay/recurring-payments-coming-soon/webhook-notifications#payment-method-notifications)​ | <p>购物者删除了已保存的付款方式。</p><h4 id="notification-payload-structure"><br></h4> |

### 通知有效载荷结构

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

#### **付款方式通知**

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

#### **`PAYMENT_METHOD_ADDED`**

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

**通知有效载荷**

```json
{
  "eventType": "PAYMENT_METHOD_ADDED",
  "timestamp": "2025-06-19T02:48:39.568907Z",
  "shopper": {
    "id": "shp_sg197861636b40021",
    "partner_shopper_id": "test_partner_123_Id",
    "email": "test@example.com"
  },
  "paymentMethod": {
    "id": "pmt_sg1978616a1900024",
    "type": "card",
    "card": {
      "lastFour": "7263",
      "expirationMonth": "04",
      "expirationYear": "2027"
    }
  }
}
```

#### 回复通知 <a href="#responding-to-notifications" id="responding-to-notifications"></a>

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

```json
{
  "ResultCode": 0
}
```

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/xun-huan-fu-kuan-ji-jiang-tui-chu/webhook-tong-zhi.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.