{
  "info": {
    "_postman_id": "kas-play-reseller-api-v1",
    "name": "KAS Play Reseller & Partner API",
    "description": "Official REST API collection for KAS Play Resellers and Partners.\n\n### Authentication\nAuthenticate your requests by adding your secret API key (`kp_live_...`) to the request header:\n`X-API-Key: {{apiKey}}`\n\n### Enterprise Performance & Best Practices\n- **Lightweight Games List**: Use `GET /api/v1/reseller/v1/games` (~15 KB) to retrieve all available games.\n- **On-Demand Packages**: Use `GET /api/v1/reseller/v1/games/:idOrSlug/packages` (~3 KB) to fetch packages for only the selected game.\n- **Filtering & Caching**: All responses are cached in-memory and support game slug and search filters.\n\n### Environments:\n- Production: `https://reseller-api.kasplay.kascambodia.com`\n- Staging: `https://458ffws9xe.execute-api.ap-southeast-1.amazonaws.com/staging`\n- Local Dev: `http://localhost:4000`",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://reseller-api.kasplay.kascambodia.com",
      "type": "string",
      "description": "API Gateway or Backend Base URL"
    },
    {
      "key": "apiKey",
      "value": "kp_live_your_api_key_here",
      "type": "string",
      "description": "Your secret developer API key generated in Partner Portal (e.g. kp_live_...)"
    },
    {
      "key": "gameSlug",
      "value": "mobile-legends-cambodia",
      "type": "string",
      "description": "Example game slug for package queries"
    },
    {
      "key": "packageId",
      "value": "51fd36aa-5698-4333-8101-2d71cf4eeca4",
      "type": "string",
      "description": "Example package ID from catalog"
    },
    {
      "key": "orderId",
      "value": "",
      "type": "string",
      "description": "Order ID returned from order placement"
    }
  ],
  "item": [
    {
      "name": "1. Reseller Profile & Balance",
      "description": "Reseller account profile, balance verification, and tier benefits.",
      "item": [
        {
          "name": "Get Reseller Profile & Live Balance",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data) {",
                  "    console.log(`[KAS Play] Connected as: ${response.data.name} (${response.data.email})`);",
                  "    console.log(`[KAS Play] Current Balance: $${response.data.balanceUsd} USD`);",
                  "    console.log(`[KAS Play] Active Tier: ${response.data.tier?.name} - ${response.data.tier?.discountLabel}`);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text",
                "description": "Your secret developer API key"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/profile",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "profile"
              ]
            },
            "description": "Returns reseller account details, real-time wallet balance in USD, active tier discount benefits, and API key rate limits."
          },
          "response": []
        }
      ]
    },
    {
      "name": "2. Game Catalog",
      "description": "Endpoints to list available games, query game details & packages, or fetch full bulk catalog.",
      "item": [
        {
          "name": "List Games (Lightweight Listing)",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data && response.data.items && response.data.items.length > 0) {",
                  "    const first = response.data.items[0];",
                  "    pm.collectionVariables.set(\"gameSlug\", first.slug || first.id);",
                  "    console.log(`[KAS Play] Retrieved ${response.data.total} games. Auto-selected slug: ${first.slug}`);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/games",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "games"
              ],
              "query": [
                {
                  "key": "page",
                  "value": "1",
                  "disabled": true,
                  "description": "Page number (default: 1)"
                },
                {
                  "key": "limit",
                  "value": "50",
                  "disabled": true,
                  "description": "Items per page (default: 50, max: 250)"
                },
                {
                  "key": "search",
                  "value": "mobile",
                  "disabled": true,
                  "description": "Optional search filter by game name or slug"
                }
              ]
            },
            "description": "Lightweight endpoint returning active games with package counts and pagination (~15 KB payload vs ~750 KB catalog). Recommended for populating game picker grids and bot catalog menus."
          },
          "response": []
        },
        {
          "name": "Get Game Details & Packages (On-Demand)",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data && response.data.packages && response.data.packages.length > 0) {",
                  "    const firstPkg = response.data.packages[0];",
                  "    pm.collectionVariables.set(\"packageId\", firstPkg.id);",
                  "    console.log(`[KAS Play] Auto-set packageId to: ${firstPkg.id} (${firstPkg.name} - $${firstPkg.priceUsd})`);",
                  "    if (response.data.fields && response.data.fields.length > 0) {",
                  "        console.log(`[KAS Play] Required account fields for this game:`, response.data.fields.map(f => f.key).join(', '));",
                  "    }",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/games/{{gameSlug}}/packages",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "games",
                "{{gameSlug}}",
                "packages"
              ]
            },
            "description": "Returns wholesale packages and required player input fields (e.g. player_id, server_id) for a specific game by slug or ID (~2-4 KB payload). Allows developers to dynamically render user account input forms."
          },
          "response": []
        },
        {
          "name": "Get Full Catalog (Bulk Sync)",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data && response.data.items && response.data.items.length > 0) {",
                  "    const firstGame = response.data.items[0];",
                  "    if (firstGame.packages && firstGame.packages.length > 0) {",
                  "        pm.collectionVariables.set(\"packageId\", firstGame.packages[0].id);",
                  "        console.log(`[KAS Play] Auto-set packageId to: ${firstGame.packages[0].id}`);",
                  "    }",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/catalog",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "catalog"
              ],
              "query": [
                {
                  "key": "game",
                  "value": "mobile-legends-cambodia",
                  "disabled": true,
                  "description": "Filter by specific game slug or category ID"
                },
                {
                  "key": "search",
                  "value": "legend",
                  "disabled": true,
                  "description": "Search keyword"
                },
                {
                  "key": "page",
                  "value": "1",
                  "disabled": true,
                  "description": "Page number (optional)"
                },
                {
                  "key": "limit",
                  "value": "20",
                  "disabled": true,
                  "description": "Items per page (optional)"
                }
              ]
            },
            "description": "Returns games and packages with your customized wholesale price (`priceUsd`) and suggested retail price (`retailPriceUsd`). Internal supplier costs and margin formulas are protected and never exposed."
          },
          "response": []
        }
      ]
    },
    {
      "name": "3. Telegram Services",
      "description": "Endpoints to query Telegram Stars/Premium products and place direct-to-username orders.",
      "item": [
        {
          "name": "List Telegram Products & Plans",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data && response.data.items && response.data.items.length > 0) {",
                  "    const first = response.data.items[0];",
                  "    if (first.packages && first.packages.length > 0) {",
                  "        pm.collectionVariables.set(\"telegramPackageId\", first.packages[0].id);",
                  "        console.log(`[KAS Play] Auto-selected Telegram packageId: ${first.packages[0].id} (${first.packages[0].name} - $${first.packages[0].priceUsd})`);",
                  "    }",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/telegram",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "telegram"
              ]
            },
            "description": "Returns available Telegram Stars and Telegram Premium packages with reseller wholesale pricing. Required account input is telegram username (without @)."
          },
          "response": []
        },
        {
          "name": "Buy Telegram Stars / Premium",
          "event": [
            {
              "listen": "prerequest",
              "script": {
                "exec": [
                  "const randomId = 'reseller_tg_' + Date.now() + '_' + Math.random().toString(36).substring(2, 9);",
                  "pm.variables.set(\"generatedIdempotencyKey\", randomId);"
                ],
                "type": "text/javascript"
              }
            },
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data && response.data.orderId) {",
                  "    pm.collectionVariables.set(\"orderId\", response.data.orderId);",
                  "    console.log(`[KAS Play] Telegram Order Placed: ${response.data.orderId}, Status: ${response.data.status}`);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"packageId\": \"{{telegramPackageId}}\",\n  \"username\": \"sopheap_dev\",\n  \"idempotencyKey\": \"{{generatedIdempotencyKey}}\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/telegram/order",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "telegram",
                "order"
              ]
            },
            "description": "Places an automated Telegram Stars or Premium order credited directly to recipient username. Features atomic wallet lock, idempotency guard, and auto-refund on failure."
          },
          "response": []
        }
      ]
    },
    {
      "name": "4. Gift Cards",
      "description": "Endpoints for digital gift card brands, live denominations & stock, and instant code/PIN fulfillment.",
      "item": [
        {
          "name": "List Gift Card Brands",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data && response.data.items && response.data.items.length > 0) {",
                  "    const first = response.data.items[0];",
                  "    pm.collectionVariables.set(\"giftCardId\", first.slug || first.id);",
                  "    console.log(`[KAS Play] Retrieved ${response.data.total} gift cards. Auto-selected: ${first.slug}`);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/gift-cards",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "gift-cards"
              ]
            },
            "description": "Returns active digital gift card brands enabled for Reseller API."
          },
          "response": []
        },
        {
          "name": "Get Gift Card Details & Denominations",
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data && response.data.cards && response.data.cards.length > 0) {",
                  "    const first = response.data.cards[0];",
                  "    pm.collectionVariables.set(\"giftCardCardId\", first.cardId);",
                  "    console.log(`[KAS Play] Auto-selected cardId: ${first.cardId} (${first.name} - $${first.priceUsd}, stock: ${first.stock})`);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/gift-cards/{{giftCardId}}/cards",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "gift-cards",
                "{{giftCardId}}",
                "cards"
              ]
            },
            "description": "Returns live card denominations, stock count, and wholesale price for a selected gift card."
          },
          "response": []
        },
        {
          "name": "Order Gift Card (Digital PIN Delivery)",
          "event": [
            {
              "listen": "prerequest",
              "script": {
                "exec": [
                  "const randomId = 'reseller_gc_' + Date.now() + '_' + Math.random().toString(36).substring(2, 9);",
                  "pm.variables.set(\"generatedIdempotencyKey\", randomId);"
                ],
                "type": "text/javascript"
              }
            },
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data && response.data.orderId) {",
                  "    pm.collectionVariables.set(\"orderId\", response.data.orderId);",
                  "    console.log(`[KAS Play] Gift Card Order Placed: ${response.data.orderId}, Status: ${response.data.status}`);",
                  "    if (response.data.cards && response.data.cards.length > 0) {",
                  "        console.log(`[KAS Play] Delivered ${response.data.cards.length} Digital Card(s):`, response.data.cards);",
                  "    }",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"categoryId\": \"{{giftCardId}}\",\n  \"cardId\": \"{{giftCardCardId}}\",\n  \"quantity\": 1,\n  \"idempotencyKey\": \"{{generatedIdempotencyKey}}\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/gift-cards/order",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "gift-cards",
                "order"
              ]
            },
            "description": "Purchases digital gift card codes with instant code/PIN delivery in response payload."
          },
          "response": []
        }
      ]
    },
    {
      "name": "5. Player Verification & Top-Up",
      "description": "Player ID validation against game servers and automated direct game top-up orders.",
      "item": [
        {
          "name": "Validate Player ID",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"slug\": \"mobile-legends-cambodia\",\n  \"fields\": {\n    \"player_id\": \"370635223\",\n    \"server_id\": \"3753\"\n  }\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/validate-player",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "validate-player"
              ]
            },
            "description": "Validates Player ID and Zone ID against game servers before placing an order."
          },
          "response": []
        },
        {
          "name": "Place Game Top-Up Order (Atomic Auto-Debit)",
          "event": [
            {
              "listen": "prerequest",
              "script": {
                "exec": [
                  "// Generate random idempotency key if not set",
                  "const randomId = 'reseller_' + Date.now() + '_' + Math.random().toString(36).substring(2, 9);",
                  "pm.variables.set(\"generatedIdempotencyKey\", randomId);"
                ],
                "type": "text/javascript"
              }
            },
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const response = pm.response.json();",
                  "if (response && response.data && response.data.orderId) {",
                  "    pm.collectionVariables.set(\"orderId\", response.data.orderId);",
                  "    console.log(`[KAS Play] Order Placed: ${response.data.orderId}, Status: ${response.data.status}`);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              },
              {
                "key": "Content-Type",
                "value": "application/json",
                "type": "text"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"packageId\": \"{{packageId}}\",\n  \"fields\": {\n    \"user_id\": \"12345678\",\n    \"zone_id\": \"1234\"\n  },\n  \"idempotencyKey\": \"{{generatedIdempotencyKey}}\"\n}"
            },
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/order",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "order"
              ]
            },
            "description": "Places an automated top-up order. Features atomic wallet lock, ~2-5s automated fulfillment, strict idempotency to prevent duplicate debits, and automatic wallet refund on vendor rejection."
          },
          "response": []
        }
      ]
    },
    {
      "name": "6. Orders & Reporting",
      "description": "Endpoints for tracking order fulfillment status and reviewing historical orders.",
      "item": [
        {
          "name": "List Order History",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/orders?page=1&limit=20",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "orders"
              ],
              "query": [
                {
                  "key": "page",
                  "value": "1"
                },
                {
                  "key": "limit",
                  "value": "20"
                },
                {
                  "key": "status",
                  "value": "failed",
                  "description": "Filter by status: pending, processing, completed, failed, refunded, cancelled",
                  "disabled": true
                },
                {
                  "key": "game",
                  "value": "mobile-legends-cambodia",
                  "description": "Filter by game slug or name",
                  "disabled": true
                }
              ]
            },
            "description": "Returns paginated orders placed through your Reseller API keys with standardized float priceUsd."
          },
          "response": []
        },
        {
          "name": "Get Order Status by ID",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "X-API-Key",
                "value": "{{apiKey}}",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{baseUrl}}/api/v1/reseller/v1/orders/{{orderId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "api",
                "v1",
                "reseller",
                "v1",
                "orders",
                "{{orderId}}"
              ]
            },
            "description": "Queries the live status of an order using its UUID. For gift cards, returns delivered digital codes and PINs."
          },
          "response": []
        }
      ]
    }
  ]
}