> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# whatsapp.payment.updated

> 在 WhatsApp 支付交易发生变更时触发。

使用 `whatsapp.payment.updated` 在您的 Webhook 端点处理此事件。

## 触发条件

在 WhatsApp 支付交易发生变更时触发。

在[配置 Webhook 端点](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)时订阅 `whatsapp.payment.updated`。

## 语法

YCloud 会向您配置的 Webhook URL 发送 HTTP `POST` 请求。以下结构展示了一种载荷变体。尖括号中的值为占位符；其类型列在 **参数**下方。可选字段和其他变体在下方进行说明。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "<ID>",
  "type": "whatsapp.payment.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappPayment": {
    "wabaId": "<WABA_ID>",
    "referenceId": "<REFERENCE_ID>",
    "status": "<STATUS>",
    "transactions": [
      {
        "id": "<ID>",
        "type": "<TYPE>",
        "status": "<STATUS>",
        "createdTimestamp": "<CREATED_TIMESTAMP_VALUE>",
        "updatedTimestamp": "<UPDATED_TIMESTAMP_VALUE>",
        "amount": {
          "value": "<VALUE_VALUE>",
          "offset": "<OFFSET_VALUE>"
        },
        "currency": "<CURRENCY>",
        "methodType": "<METHOD_TYPE>",
        "error": {
          "code": "<CODE>",
          "reason": "<REASON>"
        }
      }
    ]
  }
}
```

## 参数

在处理 JSON 请求体之前，请验证 `YCloud-Signature` HTTP 请求头。请参阅[签名验证](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)。

### 事件外层封装

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `id` | string | 是 | 事件的唯一 ID。最小长度：`6`。最大长度：`128`。 |
| `type` | string | 是 | 固定为 `whatsapp.payment.updated`。 |
| `apiVersion` | string | 是 | 用于呈现此事件的 API 版本。 |
| `createTime` | string (date-time) | 是 | 创建此事件的时间，按 [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) 格式化。例如 `2022-06-01T12:00:00.000Z`。 |

### 事件载荷

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `whatsappPayment` | object | 否 | 特定于事件的 `whatsappPayment` 载荷。 |

四个通用封装字段为必填项。载荷字段取决于事件变体。在每个对象表格中， **必填** 在其父对象存在时适用。可选字段可以省略；示例中包含某个字段并不代表该字段是必填的。

#### whatsappPayment

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `wabaId` | string | 是 | WhatsApp 商业账户 ID。 |
| `referenceId` | string | 是 | 商家提供的支付唯一标识符。区分大小写，不能为空字符串，且只能包含英文字母、数字、下划线、短划线或点，长度不得超过 35 个字符。 |
| `status` | string | 是 | 此支付的状态。<ul><li>`captured`：表示支付已成功完成。</li><li>`pending`：表示用户已尝试付款但尚未收到交易成功的信号。</li></ul> |
| `transactions` | object\[] | 否 | 包含此支付的最新交易尝试。 |

> [accordion] whatsappPayment.transactions\[]
>
> | 参数 | 类型 | 必填 | 说明 |
> | - | - | - | - |
> | `id` | string | 是 | 交易 ID。 |
> | `type` | string | 是 | 此交易的支付类型。可选值为 `billdesk`、`razorpay`、`payu` 或 `zaakpay` 之一。 |
> | `status` | string | 是 | 交易状态。可选值为 `pending`、`success` 或 `failed` 之一。 |
> | `createdTimestamp` | integer (int64) | 是 | 交易创建时间，以毫秒级 Unix 时间戳表示。 |
> | `updatedTimestamp` | integer (int64) | 是 | 交易最后更新时间，以毫秒级 Unix 时间戳表示。 |
> | `amount` | object | 是 | 用户支付的总金额。 |
> | `currency` | string | 是 | 此笔支付的币种。目前唯一支持的值为 `INR`。 |
> | `methodType` | string | 否 | 描述消费者用于支付订单的支付方式类型。可选值为 `upi`、`card`、`wallet` 或 `netbanking` 之一。支付失败时可能无法获取支付方式信息。 |
> | `error` | object | 否 | 并非所有支付尝试都会提供支付错误详情。 |

> [accordion] whatsappPayment.transactions\[].amount
>
> | 参数 | 类型 | 是否必填 | 说明 |
> | - | - | - | - |
> | `offset` | integer (int32) | 是 | 对于 `INR`，必须为 `100`。 |
> | `value` | integer (int32) | 是 | 正整数，表示金额数值乘以 offset 后的结果。例如，₹12.34 对应的值为 1234。 |
> | `description` | string | 否 | 仅用于 `tax`、`shipping` 或 `discount`。金额描述。最大字符限制为 60 个字符。最大长度：`60`。 |
> | `discount_program_name` | string | 否 | 仅用于 `discount`。用于定义激励订单的文本。如果订单包含优惠/激励，商家需要定义此信息。最大字符限制为 60 个字符。最大长度：`60`。 |

> [accordion] whatsappPayment.transactions\[].error
>
> | 参数 | 类型 | 是否必填 | 说明 |
> | - | - | - | - |
> | `code` | string | 是 | 描述由支付网关生成并由 Meta 传输给合作伙伴的支付失败原因。 |
> | `reason` | string | 是 | 以纯文本形式描述由支付网关生成并由 Meta 传输给合作伙伴的支付失败原因。 |

## 示例

以下 JSON 是传递给您的接收端的请求体。ID、电话号码和其他账户值仅作说明示意。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.payment.updated",
  "apiVersion": "v2",
  "createTime": "2024-10-10T07:08:00.000Z",
  "whatsappPayment": {
    "wabaId": "WABA-ID",
    "referenceId": "<reference-id>",
    "status": "captured",
    "transactions": [
      {
        "id": "<transaction-id>",
        "type": "razorpay",
        "status": "success",
        "createdTimestamp": 1728544066000,
        "updatedTimestamp": 1728544066000,
        "amount": {
          "value": 21000,
          "offset": 100
        },
        "currency": "INR",
        "methodType": "upi | card | wallet | netbanking",
        "error": {
          "code": "error-code",
          "reason": "error-reason"
        }
      }
    ]
  }
}
```

验证签名并持久化接收事件后，返回 `2xx` 响应。耗时较长的工作请异步处理。

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

有关场景演练，请参阅[带注释的示例](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/whatsapp-payment-updated-webhook-examples)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.