> ## 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.

# Gift Card Payment Status Notification

> When a batch gift-card payment order status changes, GatePay sends a webhook with `bizType` `PAY_GIFT_BATCH`.

Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification).

## Overview

This page documents `webhook giftCardPaymentWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above.

GatePay sends asynchronous notifications to the merchant callback URL when batch gift-card payment order status changes (`bizType` is `PAY_GIFT_BATCH`).

## Notes

* Use `externalId` or `bizId` for idempotency.
* Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/api-reference/version/100/en/common/securityAndSignature) for signing rules.

## Trigger Scenarios

* When a batch gift-card payment order status changes, GatePay sends a notification to the **callback URL** configured at merchant registration
* If delivery fails, see retry rules in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification).

**Scope**: Batch gift-card payment orders (`bizType` is `PAY_GIFT_BATCH`). For gift-card integration, see [Gift Card](/essentials/version/100/en/inflow/payment/giftcard).

## Message Structure

| Field       | Type   | Description                                                           |
| ----------- | ------ | --------------------------------------------------------------------- |
| `bizType`   | string | Always `PAY_GIFT_BATCH`                                               |
| `bizId`     | string | Batch gift-card order ID (may be an empty string; use actual payload) |
| `bizStatus` | string | Batch gift-card order status; see table below                         |
| `client_id` | string | Merchant `client_id` that created the order                           |
| `data`      | string | Business payload as a JSON string                                     |

### Example Message

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

## bizStatus Enumeration

| Value  | Description                                |
| ------ | ------------------------------------------ |
| `PAID` | Batch gift-card payment/issuance completed |

## data Field Reference

| Field           | Type   | Description                |
| --------------- | ------ | -------------------------- |
| `externalId`    | string | Merchant external order ID |
| `batchItemList` | array  | Batch gift-card line items |

### batchItemList Item Fields

| Field         | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| `amount`      | string | Line item amount                     |
| `channel_id`  | string | Customer name / channel identifier   |
| `create_time` | int64  | Creation time (milliseconds)         |
| `currency`    | string | Currency                             |
| `receiver_id` | int64  | Receiver UID                         |
| `status`      | string | Line item status, for example `PAID` |

## Callback Example

### Batch gift-card payment completed (`bizStatus=PAID`)

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

### Batch gift-card payment completed (with 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/en/openapi/gift-card-payment-callback-openapi.json webhook giftCardPaymentWebhook
openapi: 3.1.0
info:
  title: GatePay Gift Card Payment Callback API
  version: 1.0.0
  description: >-
    Asynchronous notifications for batch gift-card payment order status changes.
    When a batch gift-card payment order status changes, GatePay sends a
    notification to the merchant callback URL; `data` is a JSON string.
servers:
  - url: https://openplatform.gateapi.io
    description: Production
security: []
paths: {}

````