PlaySuper LogoPlaySuper
API Reference

Gift Card API

Complete guide for integrating PlaySuper Gift Card Voucher Marketplace API

PlaySuper Gift Card API Documentation

Getting Started

For New Studios (Onboarding Steps)

Follow these steps to get access to the Voucher Marketplace API:

Step 1: Create Your Account

  1. Go to Dev Playsuper Console
  2. For Prod Use Playsuper Console
  3. Sign up / Log in to your account

Step 2: Create an Organization

  1. Click on "Create Organization"
  2. Fill in your organization details
  3. Refresh the page after creation

Step 3: Create a Game

  1. Click on "Create Game"
  2. Fill in your game details
  3. Save the game

Step 4: Generate Your API Key

  1. Click on your game to open Game Details
  2. Navigate to View API Keys
  3. Click Generate API Key
  4. Copy the generated API key

Step 5: Share with PlaySuper Send your Game API Key to the PlaySuper team. We will:

  • Configure your voucher access settings
  • Top-up your wallet with initial credits
  • Notify you once setup is complete

Step 6: Start Integrating Once notified, use your API key in the x-api-key header to access all voucher APIs.

curl -X GET "https://api-dev.playsuper.io/vouchers/catalog/brands" \
  -H "x-api-key: YOUR_GAME_API_KEY"

Overview

The Voucher Marketplace API allows studios to purchase digital gift vouchers from various brands and distribute them to their users using the studio's prepaid wallet balance.

Authentication

All requests require your Game API Key.

Headers

HeaderRequiredDescription
x-api-keyYesYour Game API Key
Content-TypeYesapplication/json

Example

curl -X GET "https://api.playsuper.club/vouchers/catalog/brands" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json"

1. Catalog APIs

1.1 List Voucher Brands

GET /vouchers/catalog/brands

Query Parameters

ParameterTypeRequiredDefaultDescription
pagenumberNo1Page number
limitnumberNo20Items per page
categorystringNo-Filter by category
searchstringNo-Search by brand name

Example Request

curl -X GET "https://api.playsuper.club/vouchers/catalog/brands?page=1&limit=20" \
  -H "x-api-key: your-api-key-here"

Example Response

{
  "brands": [
    {
      "id": "clx123abc",
      "brandCode": "AmazonvariableXRyz82xNcsSX8Orm",
      "brandName": "Amazon",
      "brandImage": "https://cdn.gyftr.com/images/amazon.png",
      "categories": ["Shopping", "E-commerce"],
      "denomType": "DYNAMIC",
      "denominations": { "type": "DYNAMIC", "min": 10, "max": 10000 },
      "redemptionType": "ONLINE",
      "redemptionUrl": "https://www.amazon.in",
      "stockAvailable": true
    },
    {
      "id": "clx456def",
      "brandCode": "SwiggyFixedABC123",
      "brandName": "Swiggy",
      "brandImage": "https://cdn.gyftr.com/images/swiggy.png",
      "categories": ["Food", "Delivery"],
      "denomType": "FIXED",
      "denominations": { "type": "FIXED", "values": [100, 250, 500, 1000] },
      "redemptionType": "ONLINE",
      "redemptionUrl": "https://www.swiggy.com",
      "stockAvailable": true
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 150, "totalPages": 8 }
}

1.2 Get Brand Details

GET /vouchers/catalog/brands/:brandCode

Path Parameter

ParameterTypeRequiredDescription
brandCodestringYesUnique brand identifier

Example Request

curl -X GET "https://api.playsuper.club/vouchers/catalog/brands/AmazonvariableXRyz82xNcsSX8Orm" \
  -H "x-api-key: your-api-key-here"

Example Response

{
  "id": "clx123abc",
  "brandCode": "AmazonvariableXRyz82xNcsSX8Orm",
  "brandName": "Amazon",
  "brandImage": "https://cdn.gyftr.com/images/amazon.png",
  "description": "Shop for millions of products on Amazon.in",
  "categories": ["Shopping", "E-commerce"],
  "denomType": "DYNAMIC",
  "denominations": { "type": "DYNAMIC", "min": 10, "max": 10000 },
  "redemptionType": "ONLINE",
  "redemptionUrl": "https://www.amazon.in",
  "termsAndConditions": "1. Gift card is valid for 1 year from date of issue...",
  "stockAvailable": true
}

2. Stock APIs

2.1 Check Stock Availability

GET /vouchers/stock/check

Query Parameters

ParameterTypeRequiredDescription
brandCodestringYesBrand identifier
denominationnumberYesVoucher face value

Example Request

curl -X GET "https://api.playsuper.club/vouchers/stock/check?brandCode=SwiggyFixedABC123&denomination=500" \
  -H "x-api-key: your-api-key-here"

Example Response

{
  "brandCode": "SwiggyFixedABC123",
  "denomination": 500,
  "isAvailable": true,
  "quantity": 150
}

3. Order APIs

3.1 Place Voucher Order

POST /vouchers/orders/place

Request Body

FieldTypeRequiredDescription
clientOrderIdstringYesYour idempotent order ID
brandCodestringYesBrand identifier
denominationnumberYesVoucher value
quantitynumberNoDefault 1
clientMetaDataobjectNoOptional metadata

Example Request

curl -X POST "https://api.playsuper.club/vouchers/orders/place" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "clientOrderId": "ORD-2026-001234",
    "brandCode": "SwiggyFixedABC123",
    "denomination": 500,
    "quantity": 1,
    "clientMetaData": {
      "userId": "user-abc-123",
      "campaign": "winter-rewards",
      "reason": "achievement-unlock"
    }
  }'

Success Response

{
  "orderId": "vo_clx789xyz",
  "clientOrderId": "ORD-2026-001234",
  "status": "SUCCESS",
  "brandName": "Swiggy",
  "denomination": 500,
  "quantity": 1,
  "amountCharged": 475,
  "vouchers": [
    {
      "voucherCode": "SWGY-XXXX-XXXX-XXXX",
      "voucherPin": "1234",
      "expiryDate": "2027-01-15T00:00:00.000Z",
      "value": 500
    }
  ],
  "walletBalance": 9525,
  "createdAt": "2026-01-15T10:30:00.000Z"
}

Important Notes

  • clientOrderId must be unique.
  • API is fully idempotent. Reusing the same ID returns the original order.
  • Parallel requests with same ID are merged into a single order.
  • Wallet is charged only once.

Idempotency Guarantee

If multiple requests with the same clientOrderId arrive simultaneously, only one order is processed. All clients receive the same response, and no duplicate charges occur.

3.2 Check Order Status

GET /vouchers/orders/status

Query Parameters

ParameterTypeRequiredDescription
clientOrderIdstringYesYour order ID

Example Response

{
  "orderId": "vo_clx789xyz",
  "clientOrderId": "ORD-2026-001234",
  "status": "SUCCESS",
  "brandName": "Swiggy",
  "denomination": 500,
  "quantity": 1,
  "amountCharged": 475,
  "vouchers": [
    {
      "voucherCode": "SWGY-XXXX-XXXX-XXXX",
      "voucherPin": "1234",
      "expiryDate": "2027-01-15T00:00:00.000Z",
      "value": 500
    }
  ],
  "createdAt": "2026-01-15T10:30:00.000Z",
  "completedAt": "2026-01-15T10:30:02.000Z"
}

Order Statuses

StatusDescription
INITIATEDOrder created
PROCESSINGFetching voucher
SUCCESSVoucher delivered
FAILEDPayment succeeded but order failed; wallet refunded
TIMEOUTProvider timeout
REFUNDEDOrder refunded

4. Settings API

4.1 Get Studio Settings

GET /vouchers/settings

{
  "studioId": "studio-abc-123",
  "isEnabled": true,
  "environment": "PRODUCTION",
  "markupPercent": 5,
  "rateLimitPerMin": 100,
  "dailyLimit": 10000,
  "webhookUrl": null
}

5. Wallet APIs

5.1 Get Wallet Balance

GET /vouchers/wallet/balance

{
  "balance": 10000,
  "currency": "INR",
  "lastUpdated": "2026-01-15T10:30:00.000Z"
}

5.2 Get Wallet Transactions

GET /vouchers/wallet/transactions

{
  "transactions": [
    {
      "id": "wt_abc123",
      "type": "DEBIT",
      "amount": 475,
      "description": "Voucher purchase: Swiggy ₹500",
      "status": "COMPLETED",
      "source": "VOUCHER_PURCHASE",
      "metadata": { "orderId": "vo_clx789xyz", "brandName": "Swiggy" },
      "createdAt": "2026-01-15T10:30:00.000Z"
    },
    {
      "id": "wt_def456",
      "type": "CREDIT",
      "amount": 10000,
      "description": "Wallet top-up",
      "status": "COMPLETED",
      "source": "MANUAL",
      "metadata": null,
      "createdAt": "2026-01-14T09:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 25, "totalPages": 3 }
}

Error Handling

Error Format

{
  "statusCode": 400,
  "code": "ERROR_CODE",
  "message": "Human readable message",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Common Error Codes

CodeStatusDescription
INVALID_API_KEY401Missing/invalid API key
VOUCHER_ACCESS_NOT_CONFIGURED400Contact support
VOUCHER_ACCESS_DISABLED400Access disabled
BRAND_NOT_FOUND404Invalid brand
INVALID_DENOMINATION400Value not supported
INSUFFICIENT_BALANCE400Insufficient funds
ORDER_NOT_FOUND404Invalid order ID
STOCK_UNAVAILABLE400Out of stock
RATE_LIMIT_EXCEEDED429Too many requests

Best Practices

1. Idempotency

Use unique clientOrderId values. Safe to retry the same ID after timeouts.

Wallet is never double-charged.

const clientOrderId = `ORD-${Date.now()}-${crypto.randomUUID().slice(0,6)}`;

2. Check Stock Before Ordering

3. Handle Timeouts Gracefully

Poll order status on timeout.

4. Secure Voucher Codes

Store encrypted; never log in plain text.

5. Monitor Wallet Balance

Avoid failed orders due to low balance.

Environments

EnvironmentURLPurpose
Developmenthttps://dev-api.playsuper.clubTesting
Productionhttps://api.playsuper.clubLive

Webhook Integration

Complete guide for integrating PlaySuper webhooks to receive real-time transaction notifications

Deduct coins from a player POST

Next Page

On this page

PlaySuper Gift Card API DocumentationGetting StartedFor New Studios (Onboarding Steps)OverviewAuthenticationHeadersExample1. Catalog APIs1.1 List Voucher BrandsQuery ParametersExample RequestExample Response1.2 Get Brand DetailsPath ParameterExample RequestExample Response2. Stock APIs2.1 Check Stock AvailabilityQuery ParametersExample RequestExample Response3. Order APIs3.1 Place Voucher OrderRequest BodyExample RequestSuccess ResponseImportant NotesIdempotency Guarantee3.2 Check Order StatusQuery ParametersExample ResponseOrder Statuses4. Settings API4.1 Get Studio Settings5. Wallet APIs5.1 Get Wallet Balance5.2 Get Wallet TransactionsError HandlingError FormatCommon Error CodesBest Practices1. Idempotency2. Check Stock Before Ordering3. Handle Timeouts Gracefully4. Secure Voucher Codes5. Monitor Wallet BalanceEnvironmentsRelated Guides