# 1. Introduction

The gift card API solution provided by Gate Pay is designed to facilitate the instant creation and value checking of gift cards.

# 2. API Interface

# 2.1 Create Gift Card

Data Type：JSON （content-type：application/json）
Method：POST
Path: /v1/pay/gift/create
Verification Method: Signature Verification
Request Content:

Field Name Type Is Required Description

title string Y Gift card title

templateId string Y Gift card template ID

currency string Y Currency of gift card

amount string Y Amount of gift card

Field Name	Type	Is Required	Description
title	string	Y	Gift card title
templateId	string	Y	Gift card template ID
currency	string	Y	Currency of gift card
amount	string	Y	Amount of gift card

Response Content

Field Name	Type	Is Required	Description
card_num	string	Y	Card number
card_key	string	Y	Redemption code of gift card
amount	string	Y	Amount of gift card
currency	string	Y	Currency of gift card
status	string	Y	Gift card status 0 Unknown Status 1 Gift Card Pending Payment 2 Not Redeemed 3 Redeemed 4 Frozen 5 Payment Failed 6 Manual Review 7 Review Rejected 8 Review Payment Failed
card_temp_id	string	Y	Gift card template ID
creator_name	string	Y	Name of the gift card creator
create_time	string	Y	Create time

CURL Request

curl --location 'http://xxxx/v1/pay/gift/create' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId:     mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp:     1737943801377' \
--header 'x-GatePay-Nonce: 3365511030' \
--header 'x-GatePay-Signature:     e3588c4b16bd282fab43de1651abe4caf4662e3    8c2d62e71dbbca0997a60b4752b8c4adcb9ed84    babda858b4af9f35736268d8a9bf9a6f16001fb    2391f798d07' \
--data '{    "title":"api create gift card",    "templateId":"255267012439183360",    "currency":"USDT",    "amount":"0.99"}'

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

# 2.2 Get Gift Card Template List

Data Type：JSON （content-type：application/json）
Method：GET
Path: /v1/pay/gift/temp/list
Verification Method: Signature Verification
Response Content

Field Name	Type	Is Required	Description
card_temp_id	string	Y	Cover ID
image_url	string	Y	Cover Image URL
cover_type	string	Y	Cover Type

CURL

curl --location 'https://openplatform.gateapi.io/v1/pay/temp/list' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1737950081280' \
--header 'x-GatePay-Nonce: 3100797950' \
--header 'x-GatePay-Signature: d698f8fbe812a0b9142c774ccb894b8eeb8dbcce223272a32165a57c6b6c41547def66c52ea73213d98be53a5f5875377aaa8abc90be51672a57a1602bbef552'

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"
        }
    ]
}

# 2.3 Query Available Currency Balance

Data Type：JSON （content-type：application/json）
Method：GET
Path: /v1/pay/balance
Verification Method: Signature Verification
CURL

curl --location 'https://openplatform.gateapi.io/v1/pay/balance' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1737951293198' \
--header 'x-GatePay-Nonce: 5609469415' \
--header 'x-GatePay-Signature: bda8607f683f39f987f52d644738b551b7d29be5663d7c997cb7d2240e49eb1aba7b031f7bae712f6643992585705afe1ce7b4a16440b98ac13aa004a6be6499'

Response

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "ADA": "313.99963295",
        "ALGO": "0",
        "APT": "0",
        "ARB": "0",
        "ATOM": "0",
        "AVAX": "0",
        "BCH": "0",
    }
}

# 2.4 Query Gift Card

Data Type：JSON （content-type：application/json）
Method：POST
Path: /v1/pay/gift/query
Verification Method: Signature Verification
Request

Field Name Type Is Required Description

card_number string N (one of two) Gift card number

key string N (one of two) Redemption code

Field Name	Type	Is Required	Description
card_number	string	N (one of two)	Gift card number
key	string	N (one of two)	Redemption code

Response Parameters

Field Name	Type	Is Required	Description
card_num	string	Y	Gift card number
amount	string	Y	Gift card amount
currency	string	Y	Gift card currency
status	string	Y	Gift card status 0 Unknown Status 1 Gift Card Pending Payment 2 Not Redeemed 3 Redeemed 4 Frozen 5 Payment Failed 6 Manual Review 7 Review Rejected 8 Review Payment Failed
card_temp_id	string	Y	Gift card cover ID
creator_name	string	Y	Gift card creator's name
create_time	string	Y	Create time
exchange_uid	int	Y	Redeemer
key	string	Y	Redemption code
title	string	Y	Title
exchange_time	int	Y	Exchange time in standard timestamp format, measured in milliseconds

CURL

curl --location 'https://openplatform.gateapi.io/v1/pay/create/query' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1737951293198' \
--header 'x-GatePay-Nonce: 5609469415' \
--header 'x-GatePay-Signature: bda8607f683f39f987f52d644738b551b7d29be5663d7c997cb7d2240e49eb1aba7b031f7bae712f6643992585705afe1ce7b4a16440b98ac13aa004a6be6499' \
--data '{
    "card_number":"2002356433468640",
    "key":""
}'

Resonse

{
    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "card_num": "6712561472330044",
        "key": "r81T4rg3FKjt2+BYUgIn0CFqwtxp9CUSHGBFYDDJ608=",
        "title": "",
        "creator_name": "GateUser-8118f6f8",
        "amount": "0.99",
        "status": 2,
        "currency": "USDT",
        "create_time": 1737971259259,
        "exchange_uid": 0,
        "exchange_time": 1737971259259
    }
    }
}

Error Code	Description	Solution
400007	Unsupported media type	Check the supported media types for the API
400004	api_key not found in request parameters	Include the api_key provided during registration in the request header using X-GatePay-Certificate-SN
400003	Invalid request timestamp	Ensure that the X-GatePay-Timestamp is not earlier than the current time or later than 10 seconds after the request time
400020	Request does not contain the signature parameter Nonce	Include the random string used for signature generation in the request header using x-GatePay-Nonce
400002	Invalid signature	Check the signature algorithm
400000	Request parameter format error	Check the request data format
400001	Request parameter error	Check the request parameters
400621	Incorrect order amount	Check the order amount parameter
400003	Incorrect timestamp	Check if the expiration time is earlier than the current time during order creation
400201	Payment order corresponding to merchantTradeNo already exists	Check for duplicate creation
400000	Unknown error	Internal system error
400620	Duplicate creation of refund order	Check for duplicate requests
400604	The payment order to be refunded has not reached the final state, expired, or completed	Wait for the order to finish before initiating a refund
400608	Refund amount is abnormal, less than or equal to 0 or exceeds the payment order amount	Check the refund amount
400607	The number of refunds for a payment order exceeds the limit	Only one refund is supported for each payment order
500008	Merchant not found	Confirm that the X-GatePay-Certificate-SN carries the api_key issued during merchant registration
500200	No available addresses for the current	Gate address payment No available addresses for order creation
5003000	Current gift card not found	Check the gift card key or gift card numbe

Last Updated: 5/28/2025, 1:51:40 AM