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

> Gift card functionality allows merchants to create, manage, and track digital gift cards with customizable designs and templates. This guide covers the complete gift card lifecycle.

## Overview

Gift cards are digital payment instruments that enable merchants to:

* Create branded gift cards with custom cover designs
* Issue cards with specified amounts and currencies
* Track card status and redemption
* Query remaining balances

For request headers, signature rules, and callback verification, refer to [Authentication & Security](/essentials/version/100/en/common/authentication).

## API Reference

### Create Gift Card

**Endpoint:** `POST /v1/pay/gift/create`

Creates a new gift card with specified parameters. On success, returns the gift card number, key, and initial status.

#### Request Parameters

| Field        | Type   | Required | Description                                |
| ------------ | ------ | -------- | ------------------------------------------ |
| `title`      | string | Yes      | Gift card title or name                    |
| `templateId` | string | Yes      | Cover template ID for the gift card design |
| `currency`   | string | Yes      | Gift card currency (e.g., USD, EUR)        |
| `amount`     | string | Yes      | Gift card initial amount                   |

#### Response Fields

| Field        | Type   | Description                                             |
| ------------ | ------ | ------------------------------------------------------- |
| `cardNumber` | string | Unique gift card number for customer identification     |
| `key`        | string | Gift card key for activation and redemption             |
| `status`     | string | Initial gift card status (see status enumeration below) |

#### Example Request

```json theme={null}
{
  "title": "Holiday Gift Card",
  "templateId": "template_001",
  "currency": "USD",
  "amount": "100"
}
```

#### Example Response

```json theme={null}
{
  "cardNumber": "GC1234567890123456",
  "key": "KEY_abc123def456",
  "status": "CREATED"
}
```

### Query Gift Card Cover Templates

**Endpoint:** `GET /v1/pay/gift/temp/list`

Retrieves available cover templates for gift card customization.

#### Response Fields

| Field          | Type   | Description                     |
| -------------- | ------ | ------------------------------- |
| `templateId`   | string | Unique template identifier      |
| `templateName` | string | Display name of the template    |
| `coverUrl`     | string | URL to the template cover image |
| `status`       | string | Template availability status    |

### Query Balance

**Endpoint:** `GET /v1/pay/balance`

Retrieves the current balance of a gift card.

#### Query Parameters

Query by either `cardNumber` or `key` (mutually exclusive—provide only one).

| Parameter    | Type   | Required    | Description      |
| ------------ | ------ | ----------- | ---------------- |
| `cardNumber` | string | Conditional | Gift card number |
| `key`        | string | Conditional | Gift card key    |

### Query Gift Card Details

**Endpoint:** `POST /v1/pay/gift/query`

Retrieves complete gift card information including status and transaction history.

#### Query Parameters

| Parameter    | Type   | Required    | Description                 |
| ------------ | ------ | ----------- | --------------------------- |
| `cardNumber` | string | Conditional | Gift card number for lookup |
| `key`        | string | Conditional | Gift card key for lookup    |

## Gift Card Status Enumeration

| Status      | Description                                              |
| ----------- | -------------------------------------------------------- |
| `CREATED`   | Gift card has been created and is ready for distribution |
| `REDEEMED`  | Gift card balance has been fully redeemed                |
| `EXPIRED`   | Gift card has reached its expiration date                |
| `CANCELLED` | Gift card has been cancelled and is no longer valid      |

## Callback Behavior

Gift cards do not provide asynchronous callbacks. Status changes and balance updates must be retrieved through the query APIs (`POST /v1/pay/gift/query` or `GET /v1/pay/balance`).

For information on callback handling for other products, see [Notification & Callbacks](/essentials/version/100/en/common/notification).

## Error Handling

| Error Code | Description                | Applicable API     | Resolution                                                        |
| ---------- | -------------------------- | ------------------ | ----------------------------------------------------------------- |
| `400001`   | Invalid request parameters | All gift card APIs | Verify all required fields are present and correctly formatted    |
| `400007`   | Unsupported Content-Type   | All gift card APIs | Ensure `Content-Type: application/json` is set in request headers |

For additional error codes and best practices, refer to [Error Codes & Best Practices](/essentials/version/100/en/common/error).

## Integration Guide

### Minimum runnable path

```text theme={null}
List templates -> Create gift card -> Store cardNumber and key securely -> Distribute to the user -> Query card status and balance
```

For a first integration, validate the lifecycle of a single gift card first, then expand to batch issuance, campaign fulfillment, or membership-related use cases.

### Basic Flow

1. **Retrieve available templates** using `GET /v1/pay/gift/temp/list`
2. **Create a gift card** using `POST /v1/pay/gift/create` with your chosen template
3. **Store the card details** (cardNumber and key) securely
4. **Distribute the gift card** to your customer
5. **Query status** periodically using `POST /v1/pay/gift/query` or `GET /v1/pay/balance`

### Best Practices

* Store both `cardNumber` and `key` in your system for redundant lookups
* Query status before displaying balance to customers
* Implement expiration date handling in your application
* Use template IDs that align with your brand guidelines

## Related Documentation

* [Authentication & Security](/essentials/version/100/en/common/authentication)
* [Notification & Callbacks](/essentials/version/100/en/common/notification)
* [Error Codes & Best Practices](/essentials/version/100/en/common/error)
* [Account Queries and Reconciliation](/essentials/version/100/en/common/balance)
* [Payments Overview](/essentials/version/100/en/inflow/payment/payment)