whatsapp.payment.updated

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

触发条件

在 WhatsApp 支付交易发生变更时触发。在配置 Webhook 端点时订阅 whatsapp.payment.updated。

语法

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

{
  "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 请求头。请参阅签名验证。

事件外层封装

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

事件载荷

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

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

whatsappPayment

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

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	否	并非所有支付尝试都会提供支付错误详情。

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`。

whatsappPayment.transactions[].error

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

示例

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

{
  "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/1.1 200 OK

有关场景演练，请参阅带注释的示例。

开始使用

指南

接口

Webhook reference

whatsapp.payment.updated

触发条件

语法

参数

事件外层封装

事件载荷

whatsappPayment

示例

​触发条件

​语法

​参数

​事件外层封装

​事件载荷

​whatsappPayment

​示例

触发条件

语法

参数

事件外层封装

事件载荷

whatsappPayment

示例