> ## 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":""}`。通知失败时按 [通知概览](/global/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试。

## 概述

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

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

## 说明

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

## 触发情形

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

**适用范围**：批量礼品卡支付类订单（`bizType` 为 `PAY_GIFT_BATCH`）。礼品卡接入说明见 [礼品卡](/global/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 global/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: {}

````

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