{"openapi":"3.1.0","info":{"title":"INDGM Digital Top-Up Engine","version":"1.0.0","description":"Zero-markup digital asset top-up infrastructure featuring dual-handshake micro-escrow settlement, multi-supplier edge routing, and cryptographic HMAC-SHA256 authentication.","contact":{"name":"INDGM Technical Operations","url":"https:\/\/indgm.com"}},"servers":[{"url":"https:\/\/www.indgm.com\/v1","description":"Production API Gateway (v1)"}],"security":[{"ClientIdAuth":[],"ApiKeyAuth":[]},{"ClientIdAuth":[],"HmacAuth":[],"TimestampAuth":[]}],"paths":{"\/health":{"get":{"summary":"System Health & Node Telemetry","description":"Public unauthenticated endpoint returning operational status of supplier nodes and engines. Safe to poll for uptime monitoring.","security":[],"responses":{"200":{"description":"System is operational","content":{"application\/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"OPERATIONAL"},"active_nodes":{"type":"string","example":"3\/3"},"escrow_engine":{"type":"string","example":"ACTIVE"},"rate_limiter":{"type":"string","example":"ENFORCING"},"zero_markup_policy":{"type":"string","example":"ENFORCED"},"timestamp":{"type":"string","format":"date-time"}}},"example":{"status":"OPERATIONAL","active_nodes":"3\/3","escrow_engine":"ACTIVE","rate_limiter":"ENFORCING","zero_markup_policy":"ENFORCED","timestamp":"2026-09-10T12:00:00+00:00"}}}}}}},"\/catalog":{"get":{"summary":"Query Wholesale Product Catalog","description":"Returns active game SKUs with zero-markup base wholesale costs. Pricing and availability are refreshed from upstream suppliers once per hour \u2014 cache client-side for 5\u201310 minutes.","parameters":[{"name":"game","in":"query","required":false,"description":"Filter by game code (e.g. HOK_GLOBAL, MLBB, PUBGM). Strongly recommended \u2014 significantly reduces response size.","schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"Target currency for converted prices (e.g. USD, IDR, PHP, BRL).","schema":{"type":"string","default":"USD"}}],"responses":{"200":{"description":"Product list retrieved successfully","content":{"application\/json":{"schema":{"type":"object","properties":{"requested_currency":{"type":"string"},"rate_to_usd":{"type":"number","format":"float"},"count":{"type":"integer"},"skus":{"type":"array","items":{"type":"object","properties":{"game_code":{"type":"string"},"game_name":{"type":"string"},"sku_code":{"type":"string"},"display_name":{"type":"string"},"requires_zone_id":{"type":"boolean"},"wholesale_price":{"type":"object","properties":{"base_usd_cents":{"type":"integer"},"currency":{"type":"string"},"amount_raw":{"type":"number","format":"float"},"formatted":{"type":"string"},"rate_per_usd":{"type":"number","format":"float"}}}}}}}},"example":{"requested_currency":"USD","rate_to_usd":1,"count":1,"skus":[{"game_code":"HOK_GLOBAL","game_name":"Honor of Kings (Global)","sku_code":"HOK_TOKENS_80","display_name":"80 Tokens","requires_zone_id":true,"wholesale_price":{"base_usd_cents":89,"currency":"USD","amount_raw":0.89,"formatted":"$0.89","rate_per_usd":1}}]}}}},"422":{"description":"Unsupported currency requested"},"429":{"description":"Rate limit exceeded (sliding window per API key)"}}}},"\/catalog\/{identifier}\/order-information":{"get":{"summary":"Retrieve Dynamic Order Input Schema","description":"Returns dynamic form requirements (User ID, Server selector dropdowns, custom parameters) needed to dispatch account validation or top-up requests for a game or SKU.","parameters":[{"name":"identifier","in":"path","required":true,"description":"Master SKU code (e.g. HOK_TOKENS_80) or platform game code (e.g. HOK_GLOBAL).","schema":{"type":"string"},"example":"HOK_GLOBAL"}],"responses":{"200":{"description":"Dynamic input schema retrieved successfully","content":{"application\/json":{"schema":{"type":"object","properties":{"game_code":{"type":"string"},"game_name":{"type":"string"},"sku_code":{"type":"string"},"requires_validation":{"type":"boolean"},"requires_zone_id":{"type":"boolean"},"fields_count":{"type":"integer"},"fields":{"type":"array","items":{"type":"object","properties":{"field_name":{"type":"string"},"field_placeholder":{"type":"string"},"field_note":{"type":"string"},"field_type":{"type":"string","enum":["text","select","number","password","email"]},"option":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"example":{"game_code":"HOK_GLOBAL","game_name":"Honor of Kings (Global)","sku_code":"HOK_TOKENS_80","requires_validation":true,"requires_zone_id":true,"fields_count":2,"fields":[{"field_name":"User ID","field_placeholder":"Enter User ID","field_note":"Player identification number","field_type":"text","option":[]},{"field_name":"Server \/ Zone ID","field_placeholder":"Enter Server or Zone ID","field_note":"","field_type":"text","option":[]}]}}}},"404":{"description":"Target game or SKU identifier not found"},"429":{"description":"Rate limit exceeded"}}}},"\/validate-account":{"post":{"summary":"Pre-Flight Account & Nickname Verification","description":"Resolves in-game player name and server region before locking escrow funds. Does not require KYC. Call this before every topup so the user can confirm the target account is correct.","security":[],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["game_code","target_account_id"],"properties":{"game_code":{"type":"string","example":"HOK_GLOBAL"},"target_account_id":{"type":"string","example":"9928172615"},"target_zone_id":{"type":"string","example":"1001","nullable":true},"sku_code":{"type":"string","example":"HOK_TOKENS_80","nullable":true}}}}}},"responses":{"200":{"description":"Target player account verified","content":{"application\/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"game_code":{"type":"string"},"target_account_id":{"type":"string"},"target_zone_id":{"type":"string","nullable":true},"player_name":{"type":"string"},"region":{"type":"string"},"verified_via":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"example":{"valid":true,"game_code":"HOK_GLOBAL","target_account_id":"9928172615","target_zone_id":"1001","player_name":"ShadowSlayer99","region":"GLOBAL","verified_via":"Singapore Primary Edge Node","timestamp":"2026-09-11T10:45:00Z"}}}},"404":{"description":"Player ID or Zone ID not found upstream"},"422":{"description":"Validation error \u2014 malformed or missing required fields"},"429":{"description":"Rate limit exceeded"},"502":{"description":"Validation node gateway timeout \u2014 retry with backoff"}}}},"\/topup":{"post":{"summary":"Dispatch Top-Up Fulfillment Handshake","description":"Locks client prefunded escrow funds, targets the lowest-latency supplier node, verifies receipt, and settles sub-second. Requires completed KYC\/KYB verification.","security":[{"ClientIdAuth":[],"ApiKeyAuth":[],"IdempotencyAuth":[]},{"ClientIdAuth":[],"HmacAuth":[],"TimestampAuth":[],"IdempotencyAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["game_code","sku_code"],"properties":{"game_code":{"type":"string","example":"HOK_GLOBAL"},"sku_code":{"type":"string","example":"HOK_TOKENS_80"},"target_account_id":{"type":"string","example":"9928172615","description":"Required for most products. Can be omitted if passed via order_inputs."},"target_zone_id":{"type":"string","example":"1001","nullable":true},"target_extra_id":{"type":"string","nullable":true,"description":"Used for specific titles requiring a 3rd routing parameter."},"order_inputs":{"type":"array","items":{"type":"string"},"description":"Array of dynamic input values used for titles requiring specific fields (e.g., email address, password, custom ID).","example":["9928172615","1001","player@example.com"]}}}}}},"responses":{"201":{"description":"Transaction settled and verified via dual-handshake","content":{"application\/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"environment":{"type":"string"},"transaction_id":{"type":"string"},"game":{"type":"string"},"sku":{"type":"string"},"display_name":{"type":"string"},"target_account":{"type":"string"},"target_zone":{"type":"string","nullable":true},"base_cost_cents":{"type":"integer"},"fee_cents":{"type":"integer"},"total_cents":{"type":"integer"},"routed_node":{"type":"string"},"has_voucher":{"type":"boolean"},"voucher":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"pin":{"type":"string","nullable":true},"serial_number":{"type":"string","nullable":true}}},"settled_at":{"type":"string","format":"date-time"}}}}}},"202":{"description":"Transaction accepted and pending upstream supplier settlement","content":{"application\/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"environment":{"type":"string"},"transaction_id":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Insufficient prefunded escrow balance"},"403":{"description":"KYC\/KYB verification required before funds can move"},"422":{"description":"RFC 7807 Problem Detail (invalid target account, missing zone, SKU unavailable)"},"429":{"description":"Rate limit exceeded"},"502":{"description":"All upstream supplier failovers exhausted \u2014 retryable with backoff"}}}},"\/topup\/{transactionId}\/status":{"get":{"summary":"Query Transaction Settlement Status","description":"On-demand lookup of a single transaction. Prefer webhooks for status changes rather than polling this endpoint in a loop.","parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string"},"example":"01m26b8m500we7bspny4fcm1e3"}],"responses":{"200":{"description":"Settlement status and node routing record","content":{"application\/json":{"schema":{"type":"object","properties":{"transaction_id":{"type":"string"},"environment":{"type":"string"},"status":{"type":"string","enum":["PENDING","ROUTED","VALIDATING","SETTLED","FAILED","REVERSED"]},"escrow_state":{"type":"string","nullable":true},"supplier_node":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"voucher":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"pin":{"type":"string","nullable":true},"serial_number":{"type":"string","nullable":true},"delivered_at":{"type":"string","format":"date-time"}}}}}}}},"403":{"description":"KYC required"},"404":{"description":"Transaction ID not found in ledger"}}}},"\/account\/balance":{"get":{"summary":"Get Prefunded Balance & Rate Limits","description":"Real-time escrow balance statement, active tier, and sliding-window quota. Requires KYC\/KYB verification.","responses":{"200":{"description":"Real-time balance statement and sliding window quota","content":{"application\/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"environment":{"type":"string"},"tier":{"type":"string"},"prefunded_balance_cents":{"type":"integer"},"sandbox_balance_cents":{"type":"integer"},"currency":{"type":"string"},"rate_limit_per_second":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"}}},"example":{"client_id":"merchant_live_xyz123","environment":"production","tier":"standard","prefunded_balance_cents":1250000,"sandbox_balance_cents":0,"currency":"USD","rate_limit_per_second":50,"timestamp":"2026-09-11T10:45:00Z"}}}},"403":{"description":"KYC required"}}}},"\/account\/ledger":{"get":{"summary":"Audit Statement & Prefund Ledger History","description":"Immutable audit trail of balance movements, settlements, and reversals. Requires KYC\/KYB verification.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Paginated immutable ledger records","content":{"application\/json":{"schema":{"type":"object","properties":{"client_id":{"type":"string"},"current_balance":{"type":"string"},"currency":{"type":"string"},"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"amount_cents":{"type":"integer"},"amount_usd":{"type":"string"},"balance_after":{"type":"string"},"reference_id":{"type":"string","nullable":true},"note":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"403":{"description":"KYC required"}}}},"\/webhooks\/deliveries":{"get":{"summary":"Inspect Webhook Delivery Logs & Attempts","description":"Returns recent outbound webhook delivery attempts, HTTP response codes, and round-trip execution latencies. Use this to debug missed webhooks on your server.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Recent webhook delivery attempts and statuses","content":{"application\/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"target_url":{"type":"string"},"event":{"type":"string"},"response_status_code":{"type":"integer","nullable":true},"execution_time_ms":{"type":"integer","nullable":true},"attempt_number":{"type":"integer"},"status":{"type":"string"},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}}}}}}}}}},"\/webhooks\/indgm\/product":{"post":{"summary":"Real-Time Product Availability & Price Sync","description":"Inbound webhook endpoint receiving real-time stock toggles, price updates, and SKU availability alerts from the upstream supplier gateway. Authenticated via HMAC-SHA256 signature using your webhook_secret.","security":[],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["sku_code"],"properties":{"event":{"type":"string","example":"product.updated"},"sku_code":{"type":"string","example":"IND-SCY-28742"},"is_available":{"type":"boolean","example":true},"is_active":{"type":"boolean","example":true},"base_cost_cents":{"type":"integer","example":89}}}}}},"responses":{"200":{"description":"SKU availability updated and catalog cache evicted","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"sku_code":{"type":"string","example":"IND-SCY-28742"},"is_active":{"type":"boolean","example":true},"timestamp":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Invalid HMAC webhook signature"},"404":{"description":"SKU not found in local catalog mapping"},"422":{"description":"Missing required sku_code in payload"}}}}},"webhooks":{"transactionSettled":{"post":{"summary":"Transaction Settlement Event","description":"Dispatched automatically to the merchant webhook_url upon top-up confirmation. Signed with HMAC-SHA256 using your webhook_secret over {X-INDGM-Timestamp}.{raw_json_body}. Verify using the raw request body \u2014 never a re-serialized version.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"event":{"type":"string","example":"transaction.settled"},"event_id":{"type":"string","example":"01J7K8M9P0Q1R2S3T4U5V6W7X8"},"transaction_id":{"type":"string","example":"01J6G8M..."},"idempotency_key":{"type":"string","example":"tx-order-9821"},"status":{"type":"string","example":"SETTLED"},"game_code":{"type":"string","example":"HOK_GLOBAL"},"sku_code":{"type":"string","example":"HOK_TOKENS_80"},"target_account":{"type":"string","example":"9928172615"},"target_zone":{"type":"string","example":"1001","nullable":true},"cost_cents":{"type":"integer","example":99},"fee_cents":{"type":"integer","example":1},"settled_at":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Webhook received and verified successfully by merchant server"}}}},"transactionFailed":{"post":{"summary":"Transaction Failed \/ Reversal Event","description":"Dispatched automatically to the merchant webhook_url whenever an upstream supplier rejects, fails, or reverses an order fulfillment. Contains failure reasons so you can refund the user locally. Signed with HMAC-SHA256.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"event":{"type":"string","example":"transaction.failed"},"event_id":{"type":"string","example":"01J7K8M9P0Q1R2S3T4U5V6W7X8"},"transaction_id":{"type":"string","example":"01m59jykvecpc10zn0k4j953na"},"idempotency_key":{"type":"string","example":"63f4c772-6fd3-4df6-9c4f-dedd36281dd4"},"status":{"type":"string","example":"REVERSED","enum":["FAILED","REVERSED"]},"reason":{"type":"string","example":"Upstream provider out of stock \/ invalid account ID"},"game_code":{"type":"string","example":"MLBB_ID"},"sku_code":{"type":"string","example":"IND-VIP-MLA5-S13"},"target_account":{"type":"string","example":"1571346778"},"target_zone":{"type":"string","example":"16580","nullable":true},"cost_cents":{"type":"integer","example":9},"fee_cents":{"type":"integer","example":0},"settled_at":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Webhook received and failure acknowledged by merchant server"}}}},"productUpdated":{"post":{"summary":"SKU Price & Availability Change Event","description":"Dispatched in real time to your registered webhook URL whenever a product wholesale cost changes, or when a SKU is activated or disabled. Signed with HMAC-SHA256 using your webhook_secret over {X-INDGM-Timestamp}.{raw_json_body} and accompanied by X-INDGM-Event: product.updated header.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["event","event_id","sku_code","game_code","is_active","current_cost"],"properties":{"event":{"type":"string","example":"product.updated"},"event_id":{"type":"string","example":"01JBK9A1B2C3D4E5F6G7H8J9K0"},"sku_code":{"type":"string","example":"HOK_TOKENS_80"},"game_code":{"type":"string","example":"HOK_GLOBAL"},"display_name":{"type":"string","example":"80 Tokens"},"is_active":{"type":"boolean","example":true},"current_cost":{"type":"object","properties":{"base_cost_cents":{"type":"integer","example":89},"currency":{"type":"string","example":"USD"}}},"previous_cost":{"type":"object","properties":{"base_cost_cents":{"type":"integer","example":85},"is_active":{"type":"boolean","example":false}}},"updated_at":{"type":"string","format":"date-time","example":"2026-10-19T01:54:00Z"}}}}}},"responses":{"200":{"description":"Webhook received and verified successfully by merchant server"}}}}},"components":{"securitySchemes":{"ClientIdAuth":{"type":"apiKey","in":"header","name":"X-Client-ID","description":"Merchant Client ID (e.g., merchant_indgm_test or INDGMID_xxxx)."},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Client-Secret","description":"Plain client secret. Supported directly in development\/sandbox environments."},"HmacAuth":{"type":"apiKey","in":"header","name":"X-INDGM-Signature","description":"Cryptographic HMAC-SHA256 signature calculated over \"{X-INDGM-Timestamp}.{raw_body}\" using your client secret. For GET requests where the request body is empty, sign \"{timestamp}.\" with the dot retained."},"TimestampAuth":{"type":"apiKey","in":"header","name":"X-INDGM-Timestamp","description":"Unix epoch timestamp in seconds. Replays with drift exceeding \u00b1900 seconds are rejected."},"IdempotencyAuth":{"type":"apiKey","in":"header","name":"Idempotency-Key","description":"Unique UUID or order identifier per request. Identical requests sent within a 24-hour window replay original settlement payloads without re-debiting escrow balances."}},"schemas":{"ProblemDetails":{"type":"object","description":"RFC 7807 Problem Details for HTTP APIs.","properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"transaction_id":{"type":"string","nullable":true},"timestamp":{"type":"string","format":"date-time"}}}}}}