Skip to main content

​
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/giftcard/create Creates a new gift card with specified parameters. On success, returns the gift card number, key, and initial status.

​
Request Parameters

FieldTypeRequiredDescription
titlestringYesGift card title or name
templateIdstringYesCover template ID for the gift card design
currencystringYesGift card currency (e.g., USD, EUR)
amountstringYesGift card initial amount

​
Response Fields

FieldTypeDescription
cardNumberstringUnique gift card number for customer identification
keystringGift card key for activation and redemption
statusstringInitial 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/giftcard/template/list Retrieves available cover templates for gift card customization.

​
Response Fields

FieldTypeDescription
templateIdstringUnique template identifier
templateNamestringDisplay name of the template
coverUrlstringURL to the template cover image
statusstringTemplate availability status

​
Query Balance

Endpoint: GET /v1/pay/balance/query Retrieves the current balance of a gift card.

​
Query Parameters

Query by either cardNumber or key (mutually exclusive—provide only one).
ParameterTypeRequiredDescription
cardNumberstringConditionalGift card number
keystringConditionalGift card key

​
Query Gift Card Details

Endpoint: GET /v1/pay/giftcard/query Retrieves complete gift card information including status and transaction history.

​
Query Parameters

ParameterTypeRequiredDescription
cardNumberstringConditionalGift card number for lookup
keystringConditionalGift card key for lookup

​
Gift Card Status Enumeration

StatusDescription
CREATEDGift card has been created and is ready for distribution
REDEEMEDGift card balance has been fully redeemed
EXPIREDGift card has reached its expiration date
CANCELLEDGift 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 (GET /v1/pay/giftcard/query or GET /v1/pay/balance/query). For information on callback handling for other products, see Notification & Callbacks.

​
Error Handling

Error CodeDescriptionApplicable APIResolution
400001Invalid request parametersAll gift card APIsVerify all required fields are present and correctly formatted
400007Unsupported Content-TypeAll gift card APIsEnsure Content-Type: application/json is set in request headers
For additional error codes and best practices, refer to Error Codes & Best Practices.

​
Integration Guide

​
Basic Flow

  1. Retrieve available templates using GET /v1/pay/giftcard/template/list
  2. Create a gift card using POST /v1/pay/giftcard/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 GET /v1/pay/giftcard/query or GET /v1/pay/balance/query

​
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