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.
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.
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
{
"title": "Holiday Gift Card",
"templateId": "template_001",
"currency": "USD",
"amount": "100"
}
Example Response
{
"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.
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 |
Integration Guide
Minimum runnable path
List templates -> Create gift card -> Store cardNumber and key securely -> Distribute to the user -> Query card status and balance
Basic Flow
- Retrieve available templates using
GET /v1/pay/gift/temp/list
- Create a gift card using
POST /v1/pay/gift/create with your chosen template
- Store the card details (cardNumber and key) securely
- Distribute the gift card to your customer
- 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
