{ "openapi": "3.1.0", "info": { "title": "GMXAZ Bot Public API", "version": "v1", "description": "Complete OpenAPI 3.1 definition for the GMXAZ Bot Public API, including signed order webhooks." }, "servers": [ { "url": "https://gmx.az/api/v1" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/getMe": { "get": { "tags": [ "Account" ], "operationId": "get_me", "summary": "Check API account", "description": "Returns the API user, balance, and currency.\n\nUse this endpoint to verify the API key and account status.", "parameters": [], "responses": { "200": { "description": "Returns the API user, balance, and currency.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "user_id": { "type": "integer", "example": 579365494 }, "username": { "type": "string", "example": "reseller_pro" }, "balance": { "type": "string", "example": "1250.5000" }, "currency": { "type": "string", "example": "USD" }, "webhook_secret_configured": { "type": "boolean", "example": true } }, "example": { "user_id": 579365494, "username": "reseller_pro", "balance": "1250.5000", "currency": "USD", "webhook_secret_configured": true }, "additionalProperties": true } }, "example": { "success": true, "data": { "user_id": 579365494, "username": "reseller_pro", "balance": "1250.5000", "currency": "USD", "webhook_secret_configured": true } }, "additionalProperties": true }, "example": { "success": true, "data": { "user_id": 579365494, "username": "reseller_pro", "balance": "1250.5000", "currency": "USD", "webhook_secret_configured": true } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } } } } }, "/games": { "get": { "tags": [ "Catalog" ], "operationId": "games", "summary": "List games", "description": "Returns active games and their active categories.\n\nGames can be filtered by type or searched by name.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Product type filter.", "schema": { "type": "string", "enum": [ "voucher", "topup" ], "example": "topup" } }, { "name": "q", "in": "query", "required": false, "description": "Search by game name.", "schema": { "type": "string", "example": "pubg" } } ], "responses": { "200": { "description": "Returns active games and their active categories.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "PUBG Mobile" }, "type": { "type": "string", "example": "TOPUP" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Global" }, "per_page_count": { "type": "integer", "example": 12 } }, "example": { "id": 10, "name": "Global", "per_page_count": 12 }, "additionalProperties": true }, "example": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } }, "example": { "id": 1, "name": "PUBG Mobile", "type": "TOPUP", "categories": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] }, "additionalProperties": true }, "example": [ { "id": 1, "name": "PUBG Mobile", "type": "TOPUP", "categories": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } ] } }, "example": { "success": true, "data": [ { "id": 1, "name": "PUBG Mobile", "type": "TOPUP", "categories": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } ] }, "additionalProperties": true }, "example": { "success": true, "data": [ { "id": 1, "name": "PUBG Mobile", "type": "TOPUP", "categories": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } ] } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "422": { "description": "The type or q parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The type or q parameter is invalid." } } } } } } } } } }, "/categories": { "get": { "tags": [ "Catalog" ], "operationId": "categories", "summary": "List categories", "description": "Returns active categories for the selected game.\n\ngame_id is required and must be taken from the /games response.", "parameters": [ { "name": "game_id", "in": "query", "required": true, "description": "Active game ID.", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Returns active categories for the selected game.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 10 }, "name": { "type": "string", "example": "Global" }, "per_page_count": { "type": "integer", "example": 12 } }, "example": { "id": 10, "name": "Global", "per_page_count": 12 }, "additionalProperties": true }, "example": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } }, "example": { "success": true, "data": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] }, "additionalProperties": true }, "example": { "success": true, "data": [ { "id": 10, "name": "Global", "per_page_count": 12 } ] } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "422": { "description": "game_id is missing or is not an integer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "game_id is missing or is not an integer." } } } } } } }, "404": { "description": "The game was not found or is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "GAME_NOT_FOUND": { "value": { "success": false, "error": { "code": "GAME_NOT_FOUND", "message": "The game was not found or is inactive." } } } } } } } } } }, "/products": { "get": { "tags": [ "Catalog" ], "operationId": "products", "summary": "List products", "description": "Returns active products with price, stock, input fields, and pagination.\n\nFilters can be combined. Only products linked to active games and categories are returned.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "voucher or topup.", "schema": { "type": "string", "enum": [ "voucher", "topup" ], "example": "topup" } }, { "name": "game", "in": "query", "required": false, "description": "Partial game-name search.", "schema": { "type": "string", "example": "PUBG" } }, { "name": "category", "in": "query", "required": false, "description": "Partial category-name search.", "schema": { "type": "string", "example": "Global" } }, { "name": "game_id", "in": "query", "required": false, "description": "Game ID.", "schema": { "type": "integer", "example": 1 } }, { "name": "category_id", "in": "query", "required": false, "description": "Category ID.", "schema": { "type": "integer", "example": 10 } }, { "name": "q", "in": "query", "required": false, "description": "Search by product name.", "schema": { "type": "string", "example": "60 UC" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size. Current maximum: 100.", "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "Returns active products with price, stock, input fields, and pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 91 }, "name": { "type": "string", "example": "PUBG Mobile 60 UC" }, "game_id": { "type": "integer", "example": 1 }, "game": { "type": "string", "example": "PUBG Mobile" }, "category_id": { "type": "integer", "example": 10 }, "category": { "type": "string", "example": "Global" }, "type": { "type": "string", "example": "TOPUP" }, "fulfillment_type": { "type": "string", "example": "standard" }, "is_qr_login": { "type": "boolean", "example": false }, "price": { "type": "string", "example": "0.8800" }, "currency": { "type": "string", "example": "USD" }, "stock_status": { "type": "string", "example": "INFINITE" }, "stock_count": { "type": [ "string", "null" ] }, "min_qty": { "type": "integer", "example": 1 }, "max_qty": { "type": "integer", "example": 1 }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "player_id" }, "label": { "type": "string", "example": "Player ID" }, "required": { "type": "boolean", "example": true } }, "example": { "key": "player_id", "label": "Player ID", "required": true }, "additionalProperties": true }, "example": [ { "key": "player_id", "label": "Player ID", "required": true } ] }, "supports_player_validation": { "type": "boolean", "example": true } }, "example": { "id": 91, "name": "PUBG Mobile 60 UC", "game_id": 1, "game": "PUBG Mobile", "category_id": 10, "category": "Global", "type": "TOPUP", "fulfillment_type": "standard", "is_qr_login": false, "price": "0.8800", "currency": "USD", "stock_status": "INFINITE", "stock_count": null, "min_qty": 1, "max_qty": 1, "fields": [ { "key": "player_id", "label": "Player ID", "required": true } ], "supports_player_validation": true }, "additionalProperties": true }, "example": [ { "id": 91, "name": "PUBG Mobile 60 UC", "game_id": 1, "game": "PUBG Mobile", "category_id": 10, "category": "Global", "type": "TOPUP", "fulfillment_type": "standard", "is_qr_login": false, "price": "0.8800", "currency": "USD", "stock_status": "INFINITE", "stock_count": null, "min_qty": 1, "max_qty": 1, "fields": [ { "key": "player_id", "label": "Player ID", "required": true } ], "supports_player_validation": true } ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 1 } }, "example": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }, "additionalProperties": true } }, "example": { "success": true, "data": [ { "id": 91, "name": "PUBG Mobile 60 UC", "game_id": 1, "game": "PUBG Mobile", "category_id": 10, "category": "Global", "type": "TOPUP", "fulfillment_type": "standard", "is_qr_login": false, "price": "0.8800", "currency": "USD", "stock_status": "INFINITE", "stock_count": null, "min_qty": 1, "max_qty": 1, "fields": [ { "key": "player_id", "label": "Player ID", "required": true } ], "supports_player_validation": true } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 } }, "additionalProperties": true }, "example": { "success": true, "data": [ { "id": 91, "name": "PUBG Mobile 60 UC", "game_id": 1, "game": "PUBG Mobile", "category_id": 10, "category": "Global", "type": "TOPUP", "fulfillment_type": "standard", "is_qr_login": false, "price": "0.8800", "currency": "USD", "stock_status": "INFINITE", "stock_count": null, "min_qty": 1, "max_qty": 1, "fields": [ { "key": "player_id", "label": "Player ID", "required": true } ], "supports_player_validation": true } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "422": { "description": "A filter or pagination parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "A filter or pagination parameter is invalid." } } } } } } } } } }, "/validate-player": { "post": { "tags": [ "Validation" ], "operationId": "validate_player", "summary": "Validate player", "description": "Validates the player ID and, when required, the server ID.\n\nIf validation is optional, validation_optional=true may be returned and the order can continue.", "parameters": [], "responses": { "200": { "description": "Validates the player ID and, when required, the server ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "nickname": { "type": "string", "example": "PlayerOne" }, "player_name": { "type": "string", "example": "PlayerOne" }, "region": { "type": "string", "example": "TR" }, "country": { "type": "string", "example": "TR" }, "server": { "type": "string", "example": "1234" }, "nickname_verified": { "type": "boolean", "example": true }, "validation_optional": { "type": "boolean", "example": false } }, "example": { "nickname": "PlayerOne", "player_name": "PlayerOne", "region": "TR", "country": "TR", "server": "1234", "nickname_verified": true, "validation_optional": false }, "additionalProperties": true } }, "example": { "success": true, "data": { "nickname": "PlayerOne", "player_name": "PlayerOne", "region": "TR", "country": "TR", "server": "1234", "nickname_verified": true, "validation_optional": false } }, "additionalProperties": true }, "example": { "success": true, "data": { "nickname": "PlayerOne", "player_name": "PlayerOne", "region": "TR", "country": "TR", "server": "1234", "nickname_verified": true, "validation_optional": false } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "422": { "description": "A required body field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "A required body field is missing or invalid." } } } } } } }, "404": { "description": "The top-up product was not found or is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PRODUCT_NOT_FOUND": { "value": { "success": false, "error": { "code": "PRODUCT_NOT_FOUND", "message": "The top-up product was not found or is inactive." } } }, "PLAYER_NOT_FOUND": { "value": { "success": false, "error": { "code": "PLAYER_NOT_FOUND", "message": "The player could not be validated and validation is required." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "example": 91, "description": "Top-up product ID." }, "player_id": { "type": "string", "example": "51515969536", "description": "Player ID." }, "server_id": { "type": "string", "example": "1234", "description": "Server or zone ID when required." }, "input_2": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_3": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_4": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_5": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_6": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_7": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_8": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." } }, "additionalProperties": false, "required": [ "product_id", "player_id" ] }, "example": { "product_id": 91, "player_id": "51515969536", "server_id": "1234", "input_3": "CharacterName" } } } } } }, "/order": { "post": { "tags": [ "Orders" ], "operationId": "place_order", "summary": "Create order", "description": "Creates a voucher or top-up order and deducts the amount from the customer balance.\n\nThis endpoint creates a real financial operation. Use X-Idempotency-Key to protect retries. Top-up quantity is always 1.", "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "Unique retry key. Required for money-changing operations; on POST /order client_order_id can be used as the fallback key.", "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Creates a voucher or top-up order and deducts the amount from the customer balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "order_uuid": { "type": "string", "example": "a80f63d7-cabb-4e1d-a177-045f6467e7b2" }, "client_order_id": { "type": "string", "example": "order-10001" }, "product_id": { "type": "integer", "example": 91 }, "product_name": { "type": "string", "example": "PUBG Mobile 60 UC" }, "product_type": { "type": "string", "example": "TOPUP" }, "qty": { "type": "integer", "example": 1 }, "player_id": { "type": "string", "example": "51515969536" }, "server_id": { "type": "string", "example": "1234" }, "player_name": { "type": "string", "example": "PlayerOne" }, "region": { "type": "string", "example": "TR" }, "status": { "type": "string", "example": "PROCESSING" }, "price": { "type": "string", "example": "0.8800" }, "currency": { "type": "string", "example": "USD" }, "delivery": { "type": [ "string", "null" ] }, "manual_action_required": { "type": "boolean", "example": false }, "delivery_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "example": "2026-07-25T13:30:00+04:00" }, "completed_at": { "type": [ "string", "null" ] } }, "example": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "qty": 1, "player_id": "51515969536", "server_id": "1234", "player_name": "PlayerOne", "region": "TR", "status": "PROCESSING", "price": "0.8800", "currency": "USD", "delivery": null, "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": null }, "additionalProperties": true } }, "example": { "success": true, "data": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "qty": 1, "player_id": "51515969536", "server_id": "1234", "player_name": "PlayerOne", "region": "TR", "status": "PROCESSING", "price": "0.8800", "currency": "USD", "delivery": null, "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": null } }, "additionalProperties": true }, "example": { "success": true, "data": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "qty": 1, "player_id": "51515969536", "server_id": "1234", "player_name": "PlayerOne", "region": "TR", "status": "PROCESSING", "price": "0.8800", "currency": "USD", "delivery": null, "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": null } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "422": { "description": "One of the request-body fields is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "One of the request-body fields is invalid." } } }, "INVALID_QUANTITY": { "value": { "success": false, "error": { "code": "INVALID_QUANTITY", "message": "The quantity exceeds the product or API limit." } } }, "PLAYER_ID_REQUIRED": { "value": { "success": false, "error": { "code": "PLAYER_ID_REQUIRED", "message": "player_id is required for top-up orders." } } }, "SERVER_ID_REQUIRED": { "value": { "success": false, "error": { "code": "SERVER_ID_REQUIRED", "message": "server_id is required for this product." } } }, "IDEMPOTENCY_KEY_REQUIRED": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REQUIRED", "message": "A stable idempotency key is required for this operation." } } }, "IDEMPOTENCY_KEY_INVALID": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_INVALID", "message": "The idempotency key is invalid or longer than 128 characters." } } } } } } }, "404": { "description": "The product was not found or is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PRODUCT_NOT_FOUND": { "value": { "success": false, "error": { "code": "PRODUCT_NOT_FOUND", "message": "The product was not found or is inactive." } } }, "PLAYER_NOT_FOUND": { "value": { "success": false, "error": { "code": "PLAYER_NOT_FOUND", "message": "Required player validation failed." } } } } } } }, "400": { "description": "The balance is insufficient for this order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "INSUFFICIENT_FUNDS": { "value": { "success": false, "error": { "code": "INSUFFICIENT_FUNDS", "message": "The balance is insufficient for this order." } } }, "SECURITY_ERROR": { "value": { "success": false, "error": { "code": "SECURITY_ERROR", "message": "The callback URL does not meet the security requirements." } } } } } } }, "409": { "description": "The order could not be created or sent for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "OUT_OF_STOCK": { "value": { "success": false, "error": { "code": "OUT_OF_STOCK", "message": "The order could not be created or sent for processing." } } }, "IDEMPOTENCY_CONFLICT": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "The same idempotency key was reused with a different payload." } } }, "CLIENT_ORDER_ID_CONFLICT": { "value": { "success": false, "error": { "code": "CLIENT_ORDER_ID_CONFLICT", "message": "The same client_order_id is already assigned to another order." } } }, "ORDER_FAILED": { "value": { "success": false, "error": { "code": "ORDER_FAILED", "message": "The order could not be created or sent for processing." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer", "example": 91, "description": "Active product ID." }, "qty": { "type": "integer", "example": 1, "description": "Voucher maximum: 500; top-up maximum: 1." }, "player_id": { "type": "string", "example": "51515969536", "description": "Required for top-up products." }, "server_id": { "type": "string", "example": "1234", "description": "Server or zone ID when required." }, "input_2": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_3": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_4": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_5": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_6": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_7": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "input_8": { "type": "string", "example": "Additional mapped values", "description": "Additional input_2...input_8 values matching the product fields list." }, "client_order_id": { "type": "string", "example": "client-order-10001", "description": "Your own order reference. If X-Idempotency-Key is omitted on POST /order, this value also becomes the retry key." }, "callback_url": { "type": "string", "example": "https://customer.example/webhooks/bot-manager", "description": "Secure HTTPS callback URL." }, "callback_mode": { "type": "string", "enum": [ "legacy", "events" ], "example": "legacy", "description": "Callback format. Current default: legacy." } }, "additionalProperties": false, "required": [ "product_id" ] }, "example": { "product_id": 91, "qty": 1, "player_id": "51515969536", "server_id": "1234", "input_3": "CharacterName", "client_order_id": "client-order-10001", "callback_url": "https://customer.example/webhooks/bot-manager", "callback_mode": "events" } } } } } }, "/order/{id}/qr-login/status": { "get": { "tags": [ "Orders" ], "operationId": "qr_login_status", "summary": "QR Login status", "description": "Get the live QR Login fulfillment state for an owned order.\n\nReturns QR availability, version, worker state, expiry and the actions currently allowed.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Get the live QR Login fulfillment state for an owned order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "order_status": { "type": "string", "example": "PROCESSING" }, "session_status": { "type": "string", "example": "QR_READY" }, "status_label": { "type": "string", "example": "QR code is ready." }, "has_qr": { "type": "boolean", "example": true }, "qr_version": { "type": "integer", "example": 1 }, "qr_image_url": { "type": "string", "example": "https://gmx.az/api/v1/order/8821/qr-login/preview?v=1" }, "expires_at": { "type": "string", "example": "2026-08-17T16:30:00+04:00" }, "can_mark_scanned": { "type": "boolean", "example": true }, "can_request_new_qr": { "type": "boolean", "example": true }, "can_submit_otp": { "type": "boolean", "example": false }, "is_final": { "type": "boolean", "example": false } }, "example": { "order_id": 8821, "order_status": "PROCESSING", "session_status": "QR_READY", "status_label": "QR code is ready.", "has_qr": true, "qr_version": 1, "qr_image_url": "https://gmx.az/api/v1/order/8821/qr-login/preview?v=1", "expires_at": "2026-08-17T16:30:00+04:00", "can_mark_scanned": true, "can_request_new_qr": true, "can_submit_otp": false, "is_final": false }, "additionalProperties": true } }, "example": { "success": true, "data": { "order_id": 8821, "order_status": "PROCESSING", "session_status": "QR_READY", "status_label": "QR code is ready.", "has_qr": true, "qr_version": 1, "qr_image_url": "https://gmx.az/api/v1/order/8821/qr-login/preview?v=1", "expires_at": "2026-08-17T16:30:00+04:00", "can_mark_scanned": true, "can_request_new_qr": true, "can_submit_otp": false, "is_final": false } }, "additionalProperties": true }, "example": { "success": true, "data": { "order_id": 8821, "order_status": "PROCESSING", "session_status": "QR_READY", "status_label": "QR code is ready.", "has_qr": true, "qr_version": 1, "qr_image_url": "https://gmx.az/api/v1/order/8821/qr-login/preview?v=1", "expires_at": "2026-08-17T16:30:00+04:00", "can_mark_scanned": true, "can_request_new_qr": true, "can_submit_otp": false, "is_final": false } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "404": { "description": "The order was not found or belongs to another API user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "The order was not found or belongs to another API user." } } } } } } } } } }, "/order/{id}/qr-login/preview": { "get": { "tags": [ "Orders" ], "operationId": "qr_login_preview", "summary": "QR Login preview", "description": "Fetch the currently active QR image.\n\nReturns a private JPEG only while the QR is active. Authenticate this request with the same API key. Browser tags cannot attach X-API-KEY, so fetch the image as an authenticated binary/blob request and display the returned object URL.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "schema": { "type": "string", "example": "8821" } }, { "name": "v", "in": "query", "required": false, "description": "Optional QR version cache-buster.", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Fetch the currently active QR image.", "content": { "application/json": { "schema": { "type": "string", "example": "Binary image/jpeg response." }, "example": "Binary image/jpeg response." } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "404": { "description": "The order was not found or belongs to another API user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "The order was not found or belongs to another API user." } } } } } } } } } }, "/order/{id}/qr-login/scanned": { "post": { "tags": [ "Orders" ], "operationId": "qr_login_scanned", "summary": "Confirm QR scanned", "description": "Tell the assigned worker that the customer scanned the active QR.\n\nUse only after the customer actually scans the QR. This does not itself complete the order.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Tell the assigned worker that the customer scanned the active QR.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "session_status": { "type": "string", "example": "customer_scanned" }, "has_qr": { "type": "boolean", "example": true } }, "example": { "session_status": "customer_scanned", "has_qr": true }, "additionalProperties": true } }, "example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } }, "additionalProperties": true }, "example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "404": { "description": "The order was not found or belongs to another API user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "The order was not found or belongs to another API user." } } } } } } } } } }, "/order/{id}/qr-login/new-qr": { "post": { "tags": [ "Orders" ], "operationId": "qr_login_new_qr", "summary": "Request a new QR", "description": "Invalidate the current QR and request a replacement.\n\nUse when the displayed QR expired or cannot be scanned.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Invalidate the current QR and request a replacement.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "session_status": { "type": "string", "example": "awaiting_new_qr" }, "has_qr": { "type": "boolean", "example": false } }, "example": { "session_status": "awaiting_new_qr", "has_qr": false }, "additionalProperties": true } }, "example": { "success": true, "data": { "session_status": "awaiting_new_qr", "has_qr": false } }, "additionalProperties": true }, "example": { "success": true, "data": { "session_status": "awaiting_new_qr", "has_qr": false } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "404": { "description": "The order was not found or belongs to another API user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "The order was not found or belongs to another API user." } } } } } } } } } }, "/order/{id}/qr-login/otp": { "post": { "tags": [ "Orders" ], "operationId": "qr_login_otp", "summary": "Submit QR Login OTP", "description": "Send the one-time code requested by the assigned worker.\n\nOTP is accepted only during awaiting_otp and is forwarded to the assigned worker without being stored.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Send the one-time code requested by the assigned worker.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "session_status": { "type": "string", "example": "customer_scanned" }, "has_qr": { "type": "boolean", "example": true } }, "example": { "session_status": "customer_scanned", "has_qr": true }, "additionalProperties": true } }, "example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } }, "additionalProperties": true }, "example": { "success": true, "data": { "session_status": "customer_scanned", "has_qr": true } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "422": { "description": "OTP must contain 4-10 digits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "OTP must contain 4-10 digits." } } } } } } }, "404": { "description": "The order was not found or belongs to another API user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "The order was not found or belongs to another API user." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp": { "type": "string", "example": "123456", "description": "4-10 digit one-time code." } }, "additionalProperties": false, "required": [ "otp" ] }, "example": { "otp": "123456" } } } } } }, "/order/{id}": { "get": { "tags": [ "Orders" ], "operationId": "order_status", "summary": "Get order status", "description": "Finds an order by local ID, UUID, or client_order_id.\n\nReturns the current order status and voucher delivery codes when available.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "Finds an order by local ID, UUID, or client_order_id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "order_uuid": { "type": "string", "example": "a80f63d7-cabb-4e1d-a177-045f6467e7b2" }, "client_order_id": { "type": "string", "example": "order-10001" }, "product_id": { "type": "integer", "example": 17 }, "product_name": { "type": "string", "example": "Steam Wallet 10 USD" }, "product_type": { "type": "string", "example": "VOUCHER" }, "qty": { "type": "integer", "example": 2 }, "player_id": { "type": [ "string", "null" ] }, "server_id": { "type": [ "string", "null" ] }, "player_name": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "status": { "type": "string", "example": "COMPLETED" }, "price": { "type": "string", "example": "19.9800" }, "currency": { "type": "string", "example": "USD" }, "delivery": { "type": "array", "items": { "type": "string", "example": "CODE-ONE-XXXX" }, "example": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ] }, "manual_action_required": { "type": "boolean", "example": false }, "delivery_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "example": "2026-07-25T13:30:00+04:00" }, "completed_at": { "type": "string", "example": "2026-07-25T13:31:10+04:00" } }, "example": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 17, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 2, "player_id": null, "server_id": null, "player_name": null, "region": null, "status": "COMPLETED", "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": "2026-07-25T13:31:10+04:00" }, "additionalProperties": true } }, "example": { "success": true, "data": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 17, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 2, "player_id": null, "server_id": null, "player_name": null, "region": null, "status": "COMPLETED", "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": "2026-07-25T13:31:10+04:00" } }, "additionalProperties": true }, "example": { "success": true, "data": { "order_id": 8821, "order_uuid": "a80f63d7-cabb-4e1d-a177-045f6467e7b2", "client_order_id": "order-10001", "product_id": 17, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 2, "player_id": null, "server_id": null, "player_name": null, "region": null, "status": "COMPLETED", "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "created_at": "2026-07-25T13:30:00+04:00", "completed_at": "2026-07-25T13:31:10+04:00" } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "404": { "description": "The order was not found or belongs to another API user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "The order was not found or belongs to another API user." } } } } } } } } } }, "/order-status/{id}": { "get": { "tags": [ "Orders" ], "operationId": "order_status_legacy", "summary": "Legacy status endpoint", "description": "A compatibility alias for /order/{id}.\n\nUse /order/{id} for new integrations. The response and behavior are identical.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order ID, order_uuid, or client_order_id.", "schema": { "type": "string", "example": "8821" } } ], "responses": { "200": { "description": "A compatibility alias for /order/{id}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "status": { "type": "string", "example": "COMPLETED" }, "delivery": { "type": "array", "items": { "type": "string", "example": "CODE-ONE-XXXX" }, "example": [ "CODE-ONE-XXXX" ] }, "manual_action_required": { "type": "boolean", "example": false }, "delivery_message": { "type": [ "string", "null" ] } }, "example": { "order_id": 8821, "status": "COMPLETED", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null }, "additionalProperties": true } }, "example": { "success": true, "data": { "order_id": 8821, "status": "COMPLETED", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } }, "additionalProperties": true }, "example": { "success": true, "data": { "order_id": 8821, "status": "COMPLETED", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "404": { "description": "The order was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ORDER_NOT_FOUND": { "value": { "success": false, "error": { "code": "ORDER_NOT_FOUND", "message": "The order was not found." } } } } } } } } } }, "/orders": { "get": { "tags": [ "Orders" ], "operationId": "orders", "summary": "Get order history", "description": "Returns orders for the current API user with filters and pagination.\n\nCustomers can only access their own orders. per_page is limited to 100.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Order status.", "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "canceled", "cancelled", "refunded" ], "example": "completed" } }, { "name": "type", "in": "query", "required": false, "description": "Product type.", "schema": { "type": "string", "enum": [ "voucher", "topup" ], "example": "voucher" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Page size. Maximum 100.", "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "Returns orders for the current API user with filters and pagination.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "order_id": { "type": "integer", "example": 8821 }, "product_name": { "type": "string", "example": "Steam Wallet 10 USD" }, "product_type": { "type": "string", "example": "VOUCHER" }, "qty": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "COMPLETED" }, "price": { "type": "string", "example": "9.9900" }, "currency": { "type": "string", "example": "USD" }, "delivery": { "type": "array", "items": { "type": "string", "example": "CODE-ONE-XXXX" }, "example": [ "CODE-ONE-XXXX" ] }, "manual_action_required": { "type": "boolean", "example": false }, "delivery_message": { "type": [ "string", "null" ] } }, "example": { "order_id": 8821, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 1, "status": "COMPLETED", "price": "9.9900", "currency": "USD", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null }, "additionalProperties": true }, "example": [ { "order_id": 8821, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 1, "status": "COMPLETED", "price": "9.9900", "currency": "USD", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 1 } }, "example": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 }, "additionalProperties": true } }, "example": { "success": true, "data": [ { "order_id": 8821, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 1, "status": "COMPLETED", "price": "9.9900", "currency": "USD", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 } }, "additionalProperties": true }, "example": { "success": true, "data": [ { "order_id": 8821, "product_name": "Steam Wallet 10 USD", "product_type": "VOUCHER", "qty": 1, "status": "COMPLETED", "price": "9.9900", "currency": "USD", "delivery": [ "CODE-ONE-XXXX" ], "manual_action_required": false, "delivery_message": null } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 50, "total": 1 } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "422": { "description": "A filter or pagination parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "A filter or pagination parameter is invalid." } } } } } } } } } }, "/redeem-check": { "post": { "tags": [ "Redeem check" ], "operationId": "redeem_check", "summary": "Check redeem data", "description": "Checks the code and charges the amount that matches the result.\n\nThis endpoint creates a real balance operation. A maximum amount can be reserved and the unused portion refunded.", "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "description": "Required unique retry key. Reusing it with the same code returns the original result without charging or checking upstream again.", "schema": { "type": "string", "example": "4d83ae61-b98b-4d4d-bf11-58f3bc028a71" } } ], "responses": { "200": { "description": "Checks the code and charges the amount that matches the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 142 }, "status": { "type": "string", "example": "found" }, "code_masked": { "type": "string", "example": "REDE********MPLE" }, "charged_amount": { "type": "string", "example": "0.0500" }, "charged_amount_text": { "type": "string", "example": "$ 0.05" }, "balance": { "type": "string", "example": "1250.4500" }, "balance_text": { "type": "string", "example": "$ 1250.45" }, "currency_code": { "type": "string", "example": "USD" }, "currency_symbol": { "type": "string", "example": "$" }, "redemption_time": { "type": "string", "example": "2026-07-25 13:30:00" }, "expiration_time": { "type": [ "string", "null" ] }, "amount": { "type": "integer", "example": 60 }, "product_name": { "type": "string", "example": "PUBG Mobile 60 UC" }, "player_id": { "type": "string", "example": "51515969536" }, "player_name": { "type": "string", "example": "PlayerOne" }, "created_at": { "type": "string", "example": "2026-07-25 13:30:02" } }, "example": { "id": 142, "status": "found", "code_masked": "REDE********MPLE", "charged_amount": "0.0500", "charged_amount_text": "$ 0.05", "balance": "1250.4500", "balance_text": "$ 1250.45", "currency_code": "USD", "currency_symbol": "$", "redemption_time": "2026-07-25 13:30:00", "expiration_time": null, "amount": 60, "product_name": "PUBG Mobile 60 UC", "player_id": "51515969536", "player_name": "PlayerOne", "created_at": "2026-07-25 13:30:02" }, "additionalProperties": true }, "meta": { "type": "object", "properties": { "idempotent_replay": { "type": "boolean", "example": false } }, "example": { "idempotent_replay": false }, "additionalProperties": true } }, "example": { "success": true, "data": { "id": 142, "status": "found", "code_masked": "REDE********MPLE", "charged_amount": "0.0500", "charged_amount_text": "$ 0.05", "balance": "1250.4500", "balance_text": "$ 1250.45", "currency_code": "USD", "currency_symbol": "$", "redemption_time": "2026-07-25 13:30:00", "expiration_time": null, "amount": 60, "product_name": "PUBG Mobile 60 UC", "player_id": "51515969536", "player_name": "PlayerOne", "created_at": "2026-07-25 13:30:02" }, "meta": { "idempotent_replay": false } }, "additionalProperties": true }, "example": { "success": true, "data": { "id": 142, "status": "found", "code_masked": "REDE********MPLE", "charged_amount": "0.0500", "charged_amount_text": "$ 0.05", "balance": "1250.4500", "balance_text": "$ 1250.45", "currency_code": "USD", "currency_symbol": "$", "redemption_time": "2026-07-25 13:30:00", "expiration_time": null, "amount": 60, "product_name": "PUBG Mobile 60 UC", "player_id": "51515969536", "player_name": "PlayerOne", "created_at": "2026-07-25 13:30:02" }, "meta": { "idempotent_replay": false } } } } }, "503": { "description": "Public API has been disabled by the administrator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_DISABLED": { "value": { "success": false, "error": { "code": "API_DISABLED", "message": "Public API has been disabled by the administrator." } } } } } } }, "401": { "description": "The X-API-KEY header was not sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "API_KEY_MISSING": { "value": { "success": false, "error": { "code": "API_KEY_MISSING", "message": "The X-API-KEY header was not sent." } } }, "INVALID_API_KEY": { "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid or disabled, or the customer is inactive." } } } } } } }, "403": { "description": "The requesting IP address is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IP_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "IP_NOT_ALLOWED", "message": "The requesting IP address is not allowed." } } } } } } }, "429": { "description": "The per-minute request limit has been exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "RATE_LIMIT_EXCEEDED": { "value": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "The per-minute request limit has been exceeded." } } } } } } }, "422": { "description": "A stable idempotency key is required for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IDEMPOTENCY_KEY_REQUIRED": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_REQUIRED", "message": "A stable idempotency key is required for this operation." } } }, "IDEMPOTENCY_KEY_INVALID": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_KEY_INVALID", "message": "The idempotency key is invalid or longer than 128 characters." } } }, "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The code is missing or has an invalid length." } } }, "REDEEM_CHECK_FAILED": { "value": { "success": false, "error": { "code": "REDEEM_CHECK_FAILED", "message": "The redeem check failed, the service is disabled, or the balance is insufficient." } } } } } } }, "409": { "description": "The same idempotency key was reused with a different payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IDEMPOTENCY_CONFLICT": { "value": { "success": false, "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "The same idempotency key was reused with a different payload." } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "REDEEM-CODE-EXAMPLE", "description": "Code to check. 6-160 characters." } }, "additionalProperties": false, "required": [ "code" ] }, "example": { "code": "REDEEM-CODE-EXAMPLE" } } } } } } }, "webhooks": { "orderStatusChanged": { "post": { "summary": "Webhook delivery", "description": "This request represents a payload sent by the platform to your callback_url. Your receiver must verify the HMAC signature, process event_id idempotently, and return 2xx quickly.", "security": [], "parameters": [ { "name": "X-EPINBULK-Signature-V2", "in": "header", "required": true, "description": "Recommended: sha256=HMAC_SHA256(timestamp + \".\" + event_id + \".\" + raw_json_body, webhook_secret). Use the timestamp and event-id headers shown above.", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Signature-Version", "in": "header", "required": true, "description": "2", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Signature", "in": "header", "required": true, "description": "sha256=HMAC_SHA256(raw_json_body, webhook_secret)", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Timestamp", "in": "header", "required": true, "description": "ISO-8601 webhook delivery timestamp. Verify freshness when validating the V2 signature.", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Event-Id", "in": "header", "required": true, "description": "Unique UUID for the callback attempt.", "schema": { "type": "string" } }, { "name": "X-EPINBULK-Event", "in": "header", "required": true, "description": "Actual event name: order.status_changed or qr_login.*", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "legacy": { "value": { "event_id": "47c8c6ba-16a5-4089-9f62-7ae1e51d4c0f", "order_id": 8821, "client_order_id": "order-10001", "status": "COMPLETED", "product_name": "Steam Wallet 10 USD", "qty": 2, "player_id": null, "player_name": null, "server_id": null, "region": null, "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "timestamp": "2026-07-25T13:31:10+04:00" } }, "events": { "value": { "event_id": "47c8c6ba-16a5-4089-9f62-7ae1e51d4c0f", "event": "order.status_changed", "callback_mode": "events", "order_id": 8821, "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "game_id": 1, "game_name": "PUBG Mobile", "player_id": "51515969536", "player_name": "PlayerOne", "server_id": "1234", "region": "TR", "qty": 1, "price": "0.8800", "currency": "USD", "delivery": [], "manual_action_required": false, "delivery_message": null, "status": "COMPLETED", "message": "Order completed successfully.", "timestamp": "2026-07-25T13:30:10+04:00" } } } } } }, "responses": { "204": { "description": "Webhook accepted" }, "400": { "description": "Invalid payload" }, "401": { "description": "Invalid signature" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "The product_id field is required." }, "details": { "type": "object", "properties": { "max": { "type": "integer", "example": 1 } }, "example": { "max": 1 }, "additionalProperties": true } }, "example": { "code": "VALIDATION_ERROR", "message": "The product_id field is required.", "details": { "max": 1 } }, "additionalProperties": true } }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "The product_id field is required.", "details": { "max": 1 } } }, "additionalProperties": true } } }, "x-public-api-idempotency-header": "X-Idempotency-Key", "x-public-api-request-id-header": "X-Request-Id", "x-public-api-status-lifecycle": [ { "status": "PENDING", "terminal": false, "description": "The order was created and is waiting for processing." }, { "status": "PROCESSING", "terminal": false, "description": "The order is being processed." }, { "status": "COMPLETED", "terminal": true, "description": "The order was completed successfully. Voucher delivery codes are returned when applicable." }, { "status": "FAILED", "terminal": true, "description": "The order failed or was cancelled." }, { "status": "CANCELED", "terminal": true, "description": "The order was cancelled." }, { "status": "REFUNDED", "terminal": true, "description": "The amount was refunded to the balance." } ], "x-public-api-webhook-policy": { "event": "order.status_changed", "events": [ "order.status_changed", "qr_login.waiting_worker", "qr_login.worker_assigned", "qr_login.qr_ready", "qr_login.customer_scanned", "qr_login.new_qr_requested", "qr_login.otp_required", "qr_login.otp_submitted" ], "method": "POST", "content_type": "application/json", "headers": [ { "name": "X-EPINBULK-Signature-V2", "description": "Recommended: sha256=HMAC_SHA256(timestamp + \".\" + event_id + \".\" + raw_json_body, webhook_secret). Use the timestamp and event-id headers shown above." }, { "name": "X-EPINBULK-Signature-Version", "description": "2" }, { "name": "X-EPINBULK-Signature", "description": "sha256=HMAC_SHA256(raw_json_body, webhook_secret)" }, { "name": "X-EPINBULK-Timestamp", "description": "ISO-8601 webhook delivery timestamp. Verify freshness when validating the V2 signature." }, { "name": "X-EPINBULK-Event-Id", "description": "Unique UUID for the callback attempt." }, { "name": "X-EPINBULK-Event", "description": "Actual event name: order.status_changed or qr_login.*" } ], "requirements": [ "Only HTTPS URLs are accepted.", "Only port 443 is accepted.", "Private, reserved, and localhost addresses are blocked.", "Credentials in the URL are not accepted.", "Redirects are not followed.", "The receiving server must return a 2xx response." ], "retry_schedule": [ "1 → 1 minute", "2 → 5 minutes", "3 → 15 minutes", "4-6 → 60 minutes", "7-20 → 6 hours" ], "max_attempts": 20, "legacy_example": { "event_id": "47c8c6ba-16a5-4089-9f62-7ae1e51d4c0f", "order_id": 8821, "client_order_id": "order-10001", "status": "COMPLETED", "product_name": "Steam Wallet 10 USD", "qty": 2, "player_id": null, "player_name": null, "server_id": null, "region": null, "price": "19.9800", "currency": "USD", "delivery": [ "CODE-ONE-XXXX", "CODE-TWO-XXXX" ], "manual_action_required": false, "delivery_message": null, "timestamp": "2026-07-25T13:31:10+04:00" }, "events_example": { "event_id": "47c8c6ba-16a5-4089-9f62-7ae1e51d4c0f", "event": "order.status_changed", "callback_mode": "events", "order_id": 8821, "client_order_id": "order-10001", "product_id": 91, "product_name": "PUBG Mobile 60 UC", "product_type": "TOPUP", "game_id": 1, "game_name": "PUBG Mobile", "player_id": "51515969536", "player_name": "PlayerOne", "server_id": "1234", "region": "TR", "qty": 1, "price": "0.8800", "currency": "USD", "delivery": [], "manual_action_required": false, "delivery_message": null, "status": "COMPLETED", "message": "Order completed successfully.", "timestamp": "2026-07-25T13:30:10+04:00" } }, "x-public-api-limits": { "max_per_page": 100, "max_voucher_qty": 500, "max_topup_qty": 1, "default_callback_mode": "legacy" } }