Gift Card API

Integrate PlaySuper Gift Cards into your game or app — one token, two settlement models, no PlaySuper user accounts required.

The Partner Gift Card API lets any game or app sell PlaySuper's gift-card catalog to its own users. You authenticate once for a token, browse the catalog, and place orders — PlaySuper procures the voucher and returns the code.

You do not create PlaySuper user accounts and you do not deal with PlaySuper coins. You identify your own user inline on each order (for delivery), and settle with PlaySuper either from a prepaid wallet or via cash checkout.

Base URL (prod): https://api.playsuper.club
Base URL (dev): https://dev-api.playsuper.club
Currency: INR (₹)

Base URL (prod): https://api-us.playsuper.club
Currency: USD ($)
A sandbox base URL is shared during onboarding.

All partner endpoints live under /partner/v1.

Response envelope. Every successful response is wrapped: { "data": { ... }, "statusCode": 200, "message": "Success", "requestId": "...", "timestamp": "..." }. The examples below show only the data payload. Read your result from response.data.

Settlement models

Your integration uses one of two models, configured by PlaySuper on your studio. Which one you're on is returned by GET /partner/v1/gift-cards/config.

Model A — Prepaid Wallet (recommended: you use your own payment screen)

You pre-fund a PlaySuper wallet. You collect payment from your end user with your own payment SDK / screen — PlaySuper never touches that payment. When you place an order we debit your wallet the selling price, procure the voucher, and return the code instantly.

Your user pays on YOUR payment screen  →  you call POST /orders
   →  we debit your prepaid wallet (selling price)  →  voucher returned immediately

No PlaySuper-hosted payment page, no redirects — you own the checkout UX.
You keep the margin between your retail price and our selling price.
Keep the wallet funded; an order fails fast if the balance is too low.

Model B — Cash checkout (only if you have no payment gateway)

PlaySuper creates a payment session (Cashfree). We return a paymentSessionId; you render the payment with the Cashfree SDK (or we host it), the user pays us, and the order is fulfilled on payment confirmation.

PlaySuper creates a PayPal order. The paymentSessionId field in the response is a PayPal approval URL — redirect your user to it, PayPal collects the payment, and the order is fulfilled on payment confirmation.

Model A is the default and simplest — you keep your own checkout and only integrate the PlaySuper order API. Use Model B only if you have no payment gateway of your own.

1. Onboarding

Ask PlaySuper to enable External Partner mode on your studio and pick your settlement model (Wallet or Cash). For Wallet, fund your prepaid wallet.
In Console → Gift Cards → Partner API, copy your client_id (your Game API key) and generate a client_secret (shown once — store it securely).

client_id = your Game API key. client_secret is generated in the console and shown only once — copy it immediately. On reload it appears masked; if you lose it, use Rotate secret to issue a new one (the old secret stops working). If you don't set a secret at all, the key alone authenticates.

2. Get a token

Exchange your credentials for a short-lived Bearer token, then send it on every call.

curl -X POST https://api.playsuper.club/partner/v1/token \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "<your-api-key>", "client_secret": "<your-secret>" }'

curl -X POST https://api-us.playsuper.club/partner/v1/token \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "<your-api-key>", "client_secret": "<your-secret>" }'

{ "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 86400 }

Use it on every subsequent request:

Authorization: Bearer <access_token>

The token is valid for 24 hours — cache it and refresh when it expires.

3. Check your configuration

curl https://api.playsuper.club/partner/v1/gift-cards/config \
  -H "Authorization: Bearer <token>"

{ "settlement": "WALLET", "currency": "INR" }   // or "CASH"

curl https://api-us.playsuper.club/partner/v1/gift-cards/config \
  -H "Authorization: Bearer <token>"

{ "settlement": "WALLET", "currency": "USD" }   // or "CASH"

For Wallet studios, check your balance any time:

curl https://api.playsuper.club/partner/v1/gift-cards/wallet \
  -H "Authorization: Bearer <token>"

{ "balance": 25000, "currency": "INR" }

curl https://api-us.playsuper.club/partner/v1/gift-cards/wallet \
  -H "Authorization: Bearer <token>"

{ "balance": 2500, "currency": "USD" }

4. Browse the catalog

List brands (paginated):

curl "https://api.playsuper.club/partner/v1/gift-cards/brands?page=1&limit=20&search=amazon" \
  -H "Authorization: Bearer <token>"

curl "https://api-us.playsuper.club/partner/v1/gift-cards/brands?page=1&limit=20&search=nintendo" \
  -H "Authorization: Bearer <token>"

Brand detail (denominations, terms):

curl https://api.playsuper.club/partner/v1/gift-cards/brands/<brandCode> \
  -H "Authorization: Bearer <token>"

curl https://api-us.playsuper.club/partner/v1/gift-cards/brands/<brandCode> \
  -H "Authorization: Bearer <token>"

Stock check for a denomination:

curl "https://api.playsuper.club/partner/v1/gift-cards/brands/<brandCode>/stock?denomination=500" \
  -H "Authorization: Bearer <token>"

curl "https://api-us.playsuper.club/partner/v1/gift-cards/brands/<brandCode>/stock?denomination=25" \
  -H "Authorization: Bearer <token>"

FIXED brands list their denominations; DYNAMIC brands give a minValue/maxValue range.

5. Price an order (preview)

Always preview before charging your user — it returns the authoritative amount.

curl -X POST https://api.playsuper.club/partner/v1/gift-cards/orders/preview \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{ "brandCode": "<brandCode>", "denomination": 500, "quantity": 1 }'

{
  "brandCode": "<brandCode>", "brandName": "Amazon",
  "denomination": 500, "quantity": 1, "faceValue": 500,
  "settlement": "WALLET",
  "amount": 493,            // WALLET → debited from your wallet; CASH → what the user pays
  "currency": "INR"
}

curl -X POST https://api-us.playsuper.club/partner/v1/gift-cards/orders/preview \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{ "brandCode": "<brandCode>", "denomination": 25, "quantity": 1 }'

{
  "brandCode": "<brandCode>", "brandName": "Nintendo eShop",
  "denomination": 25, "quantity": 1, "faceValue": 25,
  "settlement": "WALLET",
  "amount": 24.13,          // WALLET → debited from your wallet; CASH → what the user pays
  "currency": "USD"
}

6. Place an order

Same endpoint for both models — the response differs by your settlement.

curl -X POST https://api.playsuper.club/partner/v1/gift-cards/orders \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{
    "clientOrderId": "your-unique-id-123",
    "brandCode": "<brandCode>",
    "denomination": 500,
    "quantity": 1,
    "customer": { "ref": "your-user-id", "email": "user@example.com", "phone": "9999999999" }
  }'

curl -X POST https://api-us.playsuper.club/partner/v1/gift-cards/orders \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{
    "clientOrderId": "your-unique-id-123",
    "brandCode": "<brandCode>",
    "denomination": 25,
    "quantity": 1,
    "customer": { "ref": "your-user-id", "email": "user@example.com", "phone": "+14155550100" }
  }'

clientOrderId is your idempotency key — retrying with the same value returns the same order, never a duplicate. customer identifies your user for voucher delivery and support; no PlaySuper account is created.

Model A (Wallet) response — instant voucher

{
  "orderId": "9a30…", "clientOrderId": "your-unique-id-123",
  "status": "SUCCESS",
  "brandName": "Amazon", "denomination": 500, "quantity": 1, "faceValue": 500,
  "amountDebited": 493,
  "paymentStatus": "NOT_REQUIRED",
  "customerRef": "your-user-id",
  "codes": [
    {
      "code": "XXXX-XXXX-XXXX",
      "pin": "1234",
      "providerVoucherId": "AB12-CD34EF-GHIJ",
      "value": 500,
      "expiry": "2027-04-27"
    }
  ]
}

{
  "orderId": "9a30…", "clientOrderId": "your-unique-id-123",
  "status": "SUCCESS",
  "brandName": "Nintendo eShop", "denomination": 25, "quantity": 1, "faceValue": 25,
  "amountDebited": 24.13,
  "paymentStatus": "NOT_REQUIRED",
  "customerRef": "your-user-id",
  "codes": [
    {
      "code": "XXXX-XXXX-XXXX",
      "pin": "",
      "providerVoucherId": "1342827",
      "value": 25,
      "expiry": null
    }
  ]
}

Many US brands have no PIN — pin comes back empty; expiry may be null.

Show the user providerVoucherId (the human-facing voucher number) plus pin when present. For some brands code and pin are identical (e.g. Amazon Pay).

You've already collected payment from your user on your own screen — now deliver these codes to them.

Model B (Cash) response — payment session

{
  "orderId": "9a30…", "clientOrderId": "your-unique-id-123",
  "status": "PENDING_PAYMENT", "paymentStatus": "PENDING",
  "brandName": "Amazon", "denomination": 500, "quantity": 1,
  "faceValue": 500, "cashAmount": 500,
  "customerRef": "your-user-id", "codes": [],
  "paymentSessionId": "session_xxx"
}

Complete the payment with the Cashfree SDK using paymentSessionId, then poll the order (below) until it's SUCCESS. Optionally pass a returnUrl in the request to control where the user is redirected after payment.

{
  "orderId": "9a30…", "clientOrderId": "your-unique-id-123",
  "status": "PENDING_PAYMENT", "paymentStatus": "PENDING",
  "brandName": "Nintendo eShop", "denomination": 25, "quantity": 1,
  "faceValue": 25, "cashAmount": 25,
  "customerRef": "your-user-id", "codes": [],
  "paymentSessionId": "https://www.paypal.com/checkoutnow?token=..."
}

On the US deployment paymentSessionId is a PayPal approval URL — redirect your user to it. After they approve, poll the order (below) until it's SUCCESS. Optionally pass a returnUrl in the request to control where PayPal redirects the user afterwards.

7. Order status & delivered codes

curl https://api.playsuper.club/partner/v1/gift-cards/orders/<orderId> \
  -H "Authorization: Bearer <token>"

curl https://api-us.playsuper.club/partner/v1/gift-cards/orders/<orderId> \
  -H "Authorization: Bearer <token>"

Returns the current status and, once SUCCESS, the codes. For Cash orders this also finalizes a paid-but-unconfirmed order on read.

List your orders (optionally filter by your user):

curl "https://api.playsuper.club/partner/v1/gift-cards/orders?customerRef=your-user-id&page=1&limit=25" \
  -H "Authorization: Bearer <token>"

curl "https://api-us.playsuper.club/partner/v1/gift-cards/orders?customerRef=your-user-id&page=1&limit=25" \
  -H "Authorization: Bearer <token>"

Order lifecycle

Status	Meaning
`INITIATED` / `PROCESSING`	Order created, being fulfilled
`PENDING_PAYMENT`	(Cash) awaiting the user's payment
`SUCCESS`	Voucher issued — `codes` available
`FAILED`	Could not fulfil (wallet refunded if it was debited)
`TIMEOUT`	Provider slow — resolves automatically; keep polling status
`REFUNDED`	(Cash) payment not completed → refunded

Errors

Errors return an HTTP 4xx status with { "statusCode": <code>, "message": "...", "error": "..." }. Branch on statusCode and surface message. (A few order-placement failures also carry a machine code, e.g. INSUFFICIENT_WALLET_BALANCE / PAYMENT_INIT_FAILED.)

HTTP	Example `message`	Meaning
`400`	`Brand not found or inactive`	Unknown/unavailable brand
`400`	`Denomination 37 not available for this brand`	Invalid denomination
`400`	`Studio wallet balance too low…` (`code: INSUFFICIENT_WALLET_BALANCE`)	Top up the prepaid wallet
`400`	`Failed to initiate payment…` (`code: PAYMENT_INIT_FAILED`)	(Cash) payment session could not be created
`401`	`Missing partner Bearer token`	No `Authorization` header
`401`	`Invalid or expired partner token`	Bad/expired token
`401`	`client_secret is required for this client` / `Invalid client_secret`	Token exchange failed
`404`	`Order not found`	Unknown `orderId` for your studio

Endpoint summary

Method	Path	Purpose
`POST`	`/partner/v1/token`	Get a Bearer token
`GET`	`/partner/v1/gift-cards/config`	Settlement model + currency
`GET`	`/partner/v1/gift-cards/wallet`	Prepaid wallet balance (Wallet)
`GET`	`/partner/v1/gift-cards/brands`	List brands
`GET`	`/partner/v1/gift-cards/brands/:brandCode`	Brand detail
`GET`	`/partner/v1/gift-cards/brands/:brandCode/stock`	Stock check
`POST`	`/partner/v1/gift-cards/orders/preview`	Price an order
`POST`	`/partner/v1/gift-cards/orders`	Place an order
`GET`	`/partner/v1/gift-cards/orders/:orderId`	Order status + codes
`GET`	`/partner/v1/gift-cards/orders`	List your orders

Best practices

Idempotency — use a unique clientOrderId per order; safe to retry the same value after a timeout. The wallet is never double-charged.
Preview then charge — call /orders/preview to get the exact amount before you take money from your user (Model A).
Secure the codes — store voucher code/pin encrypted; never log them in plain text.
Watch the wallet (Model A) — keep it funded to avoid INSUFFICIENT_WALLET_BALANCE.
Handle TIMEOUT — poll GET /orders/:orderId; it resolves to SUCCESS or FAILED.

This document is the current contract. After we test all endpoints post-deployment, any changes will be reflected here.

API Reference — player management, coins, and rewards
Webhooks — real-time transaction notifications
Console Setup — create your account and generate API keys

On this page