Gift Card - Gate Pay DOCS

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 via the query API
Query merchant account currency balances (separate from any single card) when needed

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, the response includes the standard status / code / data wrapper; card fields such as card_num, card_key, and numeric status are inside data.

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. `USDT`; use values supported by Gate Pay)
`amount`	string	Yes	Gift card initial amount

Response Fields

Successful responses use the common wrapper: status, code, errorMessage, and data. The gift card payload is in data:

Field	Type	Description
`card_num`	string	Unique gift card number
`card_key`	string	Redemption code
`amount`	string	Gift card amount
`currency`	string	Gift card currency
`status`	integer	Gift card status (see Gift card status codes)
`card_temp_id`	string	Template (cover) ID
`creator`	integer	Creator user ID
`creator_name`	string	Creator display name
`exchange_uid`	integer	Redeemer user ID (0 if none)
`owner`	integer	Owner user ID
`give_count`	integer	Number of times the card was gifted
`last_give_time`	integer	Last gift time (timestamp; 0 if never)
`create_time`	integer	Create time (Unix timestamp in milliseconds)

Example Request

{
  "title": "api create gift card1",
  "templateId": "255267012439183360",
  "currency": "USDT",
  "amount": "0.99"
}

Example Response

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "card_num": "2002356433468640",
    "card_key": "yJgkiqAVCwS0tC8W5D+t9iFqwtxp9CUSHGBFYDDJ608=",
    "amount": "0.99",
    "currency": "USDT",
    "status": 1,
    "card_temp_id": "255267012439183360",
    "creator": 10002,
    "creator_name": "GateUser-8118f6f8",
    "exchange_uid": 0,
    "owner": 10002,
    "give_count": 0,
    "last_give_time": 0,
    "create_time": 1737942105582
  }
}

Query Gift Card Cover Templates

Endpoint: GET /v1/pay/gift/temp/list Retrieves available cover templates for gift card customization.

Response Fields

Successful responses use the common wrapper; templates are returned in data as an array. Each item has:

Field	Type	Description
`card_temp_id`	string	Cover (template) ID — use this value as `templateId` when creating a card
`image_url`	string	Cover image URL
`title_en`	string	English title
`title_cn`	string	Chinese title
`cover_type`	string	Cover type (e.g. `theme`,`festival`,`all`)

Example Response

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": [
    {
      "card_temp_id": "293389550603997184",
      "image_url": "https://test-gateio-nft.s3.ap-northeast-1.amazonaws.com/image/688c908c72b1cb9b78039de44003b4f8de4009f5.jpg",
      "title_en": "anlitest",
      "title_cn": "anlitest常用",
      "cover_type": "theme"
    }
  ]
}

Query merchant account balances

Endpoint: GET /v1/pay/balance Returns balances for all currencies available on the current merchant account (account-level balances), not a single gift card. There are no query parameters; authentication headers apply as for other Pay APIs.

Response Fields

Field	Type	Description
`data`	object	Map of currency code to balance string (e.g. `"USDT": "1000.50"`)

Example Response

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
    "ADA": "313.99963295",
    "ALGO": "0",
    "USDT": "1000.50"
  }
}

Query Gift Card Details

Endpoint: POST /v1/pay/gift/query Retrieves gift card details by card number or redemption code. Send a JSON body (not query string). Provide card_number and/or key; if both are sent, key takes priority.

Request body

Field	Type	Required	Description
`card_number`	string	One of two	Gift card number
`key`	string	One of two	Redemption code

Response Fields (`data`)

Field	Type	Description
`card_num`	string	Gift card number
`key`	string	Redemption code
`title`	string	Title
`creator_name`	string	Creator display name
`amount`	string	Gift card amount
`status`	integer	Status code (see below)
`currency`	string	Currency
`card_temp_id`	string	Cover ID
`create_time`	integer	Create time (milliseconds)
`exchange_uid`	integer	Redeemer ID
`exchange_time`	integer	Exchange time (milliseconds)

Example Request

{
  "card_number": "5202710871862281"
}

Example Response

{
  "status": "SUCCESS",
  "code": "000000",
  "errorMessage": "",
  "data": {
      "card_num": "5607423016280059",
      "key": "94Q1UV7RMUEMNINL",
      "title": "anliAPI",
      "creator_name": "xuyi006",
      "amount": "0.0001",
      "status": 3,
      "currency": "USDT",
      "create_time": 1744717081334,
      "exchange_uid": 39992131,
      "exchange_time": 1776838077478,
      "card_temp_id": "346749173549240320"
  }
}

Gift card status codes

The status field on gift card records is an integer. Values match the platform enumeration (e.g. GiftCardStatusEnum):

Code	Meaning
`0`	Unknown
`1`	Pending payment
`2`	Not redeemed
`3`	Redeemed (cashed out)
`4`	Frozen
`5`	Payment failed
`6`	Manual review
`7`	Review rejected
`8`	Review payment failed
`9`	Soft-deleted
`10`	Gifting in progress
`11`	Voided

Callback Behavior

Gift cards do not provide asynchronous callbacks. Card status and details should be retrieved with POST /v1/pay/gift/query. Use GET /v1/pay/balance when you need the merchant account’s multi-currency balances, not a per-card balance. For information on callback handling for other products, see Notification & Callbacks.

Error Handling

Common platform error codes and how to resolve them are listed below. When querying a gift card, an incorrect key or card number may return 5003000.

Error Code	Description	Resolution
`400007`	Unsupported media type	Check which media types the API accepts
`400004`	`api_key` not found in the request	In the request header, pass the `api_key` from registration using `X-GatePay-Certificate-ClientId`
`400020`	Missing Nonce random string for signing	In the request header, pass the random string used to build the signature using `X-GatePay-Nonce`
`400002`	Invalid signature	Verify the signing algorithm
`400000`	Request parameter format error	Check the request payload format
`400001`	Request parameter error	Check the request parameters
`400621`	Order amount is incorrect	Check the order amount fields
`400003`	Timestamp is incorrect	Check whether X-GatePay-Timestamp is earlier than the current time or more than 10 seconds ahead of the request time
`400201`	A payment order for this merchant’s `merchantTradeNo` already exists	Check for duplicate creation
`400620`	Duplicate refund order	Check for duplicate requests
`400604`	The address payment order to refund is not in a terminal state (expired or completed)	Wait until the order reaches a final state before refunding
`400608`	Refund amount invalid: ≤ 0 or exceeds the payment order amount	Check the refund amount
`400607`	Refund attempts for one payment order exceed the limit	Only one refund is allowed per payment order
`500008`	Merchant not found	Confirm `X-GatePay-Certificate-ClientId` carries the `api_key` issued at merchant registration
`500200`	No Gate address-payment address is available	No payout address available when creating the order
`5003000`	Gift card not found	Check the gift card key or card number

For more error codes and best practices, see Error Codes & Best Practices.

Integration Guide

Minimum runnable path

List templates -> Create gift card -> Store card_num and card_key securely -> Distribute to the user -> Query card details (POST /v1/pay/gift/query); use GET /v1/pay/balance for merchant account balances if needed

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

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 (card_num and card_key from the create response) securely
Distribute the gift card to your customer
Query card details with POST /v1/pay/gift/query (body: card_number and/or key). Use GET /v1/pay/balance only for merchant account currency balances

Best Practices

Store both card_num and card_key for lookups; the query API accepts card_number or key in the JSON body (if both are sent, key wins)
Use integer status codes from Gift card status codes when branching in your app
Use card_temp_id from the template list as templateId when creating a card
GET /v1/pay/balance reflects merchant account funds by currency, not an individual gift card’s remaining value

​Overview

​API Reference

​Create Gift Card

​Request Parameters

​Response Fields

​Example Request

​Example Response

​Query Gift Card Cover Templates

​Response Fields

​Example Response

​Query merchant account balances

​Response Fields

​Example Response

​Query Gift Card Details

​Request body

​Response Fields (data)

​Example Request

​Example Response

​Gift card status codes

​Callback Behavior

​Error Handling

​Integration Guide

​Minimum runnable path

​Basic Flow

​Best Practices

​Related Documentation

Overview

API Reference

Create Gift Card

Request Parameters

Response Fields

Example Request

Example Response

Query Gift Card Cover Templates

Response Fields

Example Response

Query merchant account balances

Response Fields

Example Response

Query Gift Card Details

Request body

Response Fields (`data`)

Example Request

Example Response

Gift card status codes

Callback Behavior

Error Handling

Integration Guide

Minimum runnable path

Basic Flow

Best Practices

Related Documentation