礼品卡支付状态通知

{
  "bizType": "PAY_GIFT_BATCH",
  "bizId": "",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[],\"externalId\":\"\"}"
}

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

WEBHOOK

giftCardPaymentNotify

{
  "bizType": "PAY_GIFT_BATCH",
  "bizId": "",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[],\"externalId\":\"\"}"
}

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

概述

本页说明 webhook giftCardPaymentNotify。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。批量礼品卡支付订单状态变更时，GatePay 向商户配置的 callback URL 发送异步通知（bizType 为 PAY_GIFT_BATCH）。

说明

建议基于 externalId 或 bizId 做幂等处理。
验签、重试、data 解析与成功应答见通知概览；签名规则见安全与签名。

触发情形

批量礼品卡支付订单状态发生改变时，GatePay 向商户注册时配置的 callback URL 发送通知
若通知投递失败，重试规则见通知概览。

适用范围：批量礼品卡支付类订单（bizType 为 PAY_GIFT_BATCH）。礼品卡接入说明见礼品卡。

消息结构

字段名	类型	说明
`bizType`	string	固定为 `PAY_GIFT_BATCH`
`bizId`	string	批量礼品卡订单 ID（可能为空字符串，以实际为准）
`bizStatus`	string	批量礼品卡订单状态，见下表
`client_id`	string	创建订单的商户 `client_id`
`data`	string	业务数据 JSON 字符串

消息结构示例

{
  "bizType": "PAY_GIFT_BATCH",
  "bizId": "",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[],\"externalId\":\"\"}"
}

bizStatus 枚举值

值	说明
`PAID`	批量礼品卡支付/发卡完成

data 字段说明

字段名	类型	说明
`externalId`	string	商户外部单号
`batchItemList`	array	批量礼品卡子项列表

batchItemList 子项字段

字段名	类型	说明
`amount`	string	子项金额
`channel_id`	string	客户名称 / 渠道标识
`create_time`	int64	创建时间（毫秒）
`currency`	string	币种
`receiver_id`	int64	接收方 UID
`status`	string	子项状态，例如 `PAID`

回调示例

批量礼品卡支付完成（`bizStatus=PAID`）

{
  "bizType": "PAY_GIFT_BATCH",
  "bizId": "",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[],\"externalId\":\"\"}"
}

批量礼品卡支付完成（含 batchItemList 子项）

{
  "bizType": "PAY_GIFT_BATCH",
  "bizId": "79553020665790541",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[{\"amount\":\"10.00\",\"channel_id\":\"\",\"create_time\":1780017207390,\"currency\":\"USDT\",\"receiver_id\":22112573,\"status\":\"PAID\"}],\"externalId\":\"gift-order-20260329\"}"
}

请求体

application/json

bizType

enum<string>

必填

业务类型，固定为 PAY_GIFT_BATCH。

可用选项:

PAY_GIFT_BATCH

bizId

string

必填

批量礼品卡订单 ID。

bizStatus

enum<string>

必填

批量礼品卡订单状态，常见为 PAID（支付/发卡完成）。

可用选项:

PAID

data

string

必填

业务数据 JSON 字符串，解析后结构见 giftCardPaymentData。

client_id

string

创建订单的商户 client_id。

giftCardPaymentData

object

data 解析后的批量礼品卡支付明细。

Show child attributes

description

any

响应

200 - application/json

返回 HTTP 200 表示商户已成功接收通知。

商户接收通知后的响应体。

returnCode

string

必填

返回状态码，SUCCESS 表示成功。

returnMessage

string | null

返回说明，成功时可为空。

批量转账状态通知

退款状态通知

⌘I

Documentation Index

​概述

​说明

​触发情形

​消息结构

​消息结构示例

​bizStatus 枚举值

​data 字段说明

​batchItemList 子项字段

​回调示例

​批量礼品卡支付完成（bizStatus=PAID）

​批量礼品卡支付完成（含 batchItemList 子项）

请求体

响应

概述

说明

触发情形

消息结构

消息结构示例

bizStatus 枚举值

data 字段说明

batchItemList 子项字段

回调示例

批量礼品卡支付完成（`bizStatus=PAID`）

批量礼品卡支付完成（含 batchItemList 子项）