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

# 礼品卡支付状态通知

> 批量礼品卡支付订单状态变更时，GatePay 发送 `bizType` 为 `PAY_GIFT_BATCH` 的 webhook 通知。

商户须校验签名，处理成功后返回 `{"returnCode":"SUCCESS","returnMessage":""}`。通知失败时按 [通知概览](/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试。

## 概述

本页说明 `webhook giftCardPaymentNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。

批量礼品卡支付订单状态变更时，GatePay 向商户配置的 callback URL 发送异步通知（`bizType` 为 `PAY_GIFT_BATCH`）。

## 说明

* 建议基于 `externalId` 或 `bizId` 做幂等处理。
* 验签、重试、`data` 解析与成功应答见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。

## 触发情形

* 批量礼品卡支付订单状态发生改变时，GatePay 向商户注册时配置的 **callback URL** 发送通知
* 若通知投递失败，重试规则见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)。

**适用范围**：批量礼品卡支付类订单（`bizType` 为 `PAY_GIFT_BATCH`）。礼品卡接入说明见 [礼品卡](/essentials/version/100/cn/inflow/payment/giftcard)。

## 消息结构

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

### 消息结构示例

```json theme={null}
{
  "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`）

```json theme={null}
{
  "bizType": "PAY_GIFT_BATCH",
  "bizId": "",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[],\"externalId\":\"\"}"
}
```

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

```json theme={null}
{
  "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\"}"
}
```


## OpenAPI

````yaml api-reference/version/100/cn/openapi/gift-card-payment-callback-openapi.json webhook giftCardPaymentNotify
openapi: 3.1.0
info:
  title: GatePay 礼品卡支付回调 API
  version: 1.0.0
  description: >-
    批量礼品卡支付订单状态异步通知。当批量礼品卡支付订单状态发生变化时，GatePay 向商户注册的 callback URL 发送通知；`data` 为
    JSON 字符串。
servers:
  - url: https://openplatform.gateapi.io
    description: 生产环境
security: []
paths: {}

````