{
    "openapi": "3.1.0",
    "info": {
        "title": "Warya Shop Reseller API",
        "version": "1.0.0",
        "description": "Warya Shop customer API for catalog, wallet balance, player validation, orders and voucher delivery."
    },
    "servers": [
        {
            "url": "https://api.waryashop.org/api/v1",
            "description": "Warya Shop API v1"
        }
    ],
    "tags": [
        {
            "name": "Account"
        },
        {
            "name": "Catalog"
        },
        {
            "name": "Player"
        },
        {
            "name": "Orders"
        }
    ],
    "paths": {
        "/balance": {
            "get": {
                "tags": [
                    "Account"
                ],
                "summary": "Get wallet balance",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Current balance",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BalanceResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/games": {
            "get": {
                "tags": [
                    "Catalog"
                ],
                "summary": "List active games and products",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Active catalog",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GamesResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/games/{code}/catalogue": {
            "get": {
                "tags": [
                    "Catalog"
                ],
                "summary": "List packages and sale prices",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "description": "Game or product code",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Game catalogue",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/games/{code}/fields": {
            "get": {
                "tags": [
                    "Catalog"
                ],
                "summary": "Get required order fields",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "description": "Game or product code",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Required fields",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/games/{code}/servers": {
            "get": {
                "tags": [
                    "Catalog"
                ],
                "summary": "Get available servers or regions",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "description": "Game or product code",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Server list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/player/validate": {
            "post": {
                "tags": [
                    "Player"
                ],
                "summary": "Validate a player account",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PlayerValidationRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Player is valid",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/orders": {
            "post": {
                "tags": [
                    "Orders"
                ],
                "summary": "Create an idempotent order",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateOrderRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Order accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CreateOrderResponse"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Insufficient balance",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationFailed"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            },
            "get": {
                "tags": [
                    "Orders"
                ],
                "summary": "List your orders",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 25
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated orders",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/orders/{order_id}": {
            "get": {
                "tags": [
                    "Orders"
                ],
                "summary": "Get one order",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "order_id",
                        "in": "path",
                        "required": true,
                        "description": "Public order ID, for example WR-20260707-8F3KD",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Order details",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/transactions": {
            "get": {
                "tags": [
                    "Account"
                ],
                "summary": "List wallet transactions",
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 25
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated transactions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key",
                "description": "Create a key in the Warya dashboard."
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "Missing or invalid API key",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "Account blocked or IP not allowed",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            },
            "NotFound": {
                "description": "Resource not found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "Rate limit exceeded",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        }
                    }
                }
            },
            "ValidationFailed": {
                "description": "Request validation failed",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object"
                        }
                    }
                }
            }
        },
        "schemas": {
            "ErrorResponse": {
                "type": "object",
                "required": [
                    "success",
                    "error_code",
                    "message"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": false
                    },
                    "error_code": {
                        "type": "string",
                        "example": "INVALID_REQUEST"
                    },
                    "message": {
                        "type": "string"
                    }
                }
            },
            "BalanceResponse": {
                "type": "object",
                "required": [
                    "success",
                    "balance",
                    "locked_balance",
                    "currency"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": true
                    },
                    "balance": {
                        "type": "string",
                        "example": "25.500000"
                    },
                    "locked_balance": {
                        "type": "string",
                        "example": "0.000000"
                    },
                    "currency": {
                        "type": "string",
                        "example": "USD"
                    }
                }
            },
            "GamesResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": true
                    },
                    "games": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Game"
                        }
                    }
                }
            },
            "Game": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "example": "pubgm"
                    },
                    "name": {
                        "type": "string",
                        "example": "PUBG Mobile"
                    },
                    "image": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "uri"
                    },
                    "name_fa": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },
            "PlayerValidationRequest": {
                "type": "object",
                "required": [
                    "game",
                    "player_id"
                ],
                "properties": {
                    "game": {
                        "type": "string",
                        "example": "pubgm"
                    },
                    "player_id": {
                        "type": "string",
                        "example": "12345678"
                    },
                    "server_id": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "charname": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },
            "CreateOrderRequest": {
                "type": "object",
                "required": [
                    "game",
                    "catalogue_name"
                ],
                "properties": {
                    "game": {
                        "type": "string",
                        "example": "pubgm"
                    },
                    "catalogue_name": {
                        "type": "string",
                        "example": "60 UC"
                    },
                    "player_id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "12345678"
                    },
                    "server_id": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "charname": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "customer_reference": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 191
                    },
                    "callback_url": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "uri",
                        "maxLength": 500
                    },
                    "idempotency_key": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 191,
                        "description": "A unique client-generated key. Reuse only for the identical order."
                    }
                }
            },
            "CreateOrderResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": true
                    },
                    "order_id": {
                        "type": "string",
                        "example": "WR-20260707-8F3KD"
                    },
                    "status": {
                        "type": "string",
                        "example": "processing"
                    },
                    "charged": {
                        "type": "string",
                        "example": "0.950000"
                    },
                    "currency": {
                        "type": "string",
                        "example": "USD"
                    }
                }
            }
        }
    }
}