{ "openapi": "3.1.0", "info": { "title": "Mas4games Dealer API", "version": "1.0.0", "description": "Sell our products automatically on your site, in your app or in your panel. Orders are paid from your balance at once and codes arrive in seconds; every step is predictable, documented and testable.\n\nSend your secret key in the Authorization header of every request: Authorization: Bearer m4gc_live_…\n\nAmounts are whole numbers in the smallest unit: `{\"amount\": 41990, \"currency\": \"TRY\"}` means 419.90 TL. No fractions are ever used, so there are no rounding errors. The number of decimals is `currency_decimals` in `GET /me`." }, "servers": [ { "url": "https://api.mas4games.com/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account" }, { "name": "Catalog" }, { "name": "Orders" }, { "name": "Balance" }, { "name": "Webhook endpoint" } ], "paths": { "/me": { "get": { "operationId": "me", "tags": [ "Account" ], "summary": "Account", "description": "Returns your account, your balances and the key in use (its mode, allowed IPs and webhook address). With a test key the balance is the sandbox's made-up one (`1000000` in the key's currency).", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "id": 18452, "name": "Örnek Bayi", "email": "bayi@example.com", "email_verified": true, "customer_type": "Bayi", "created_at": "2024-03-12T09:41:00Z", "currency": "TRY", "currency_decimals": 2, "balances": [ { "amount": 1245075, "currency": "TRY", "decimals": 2 } ], "key": { "mode": "live", "created_at": "2026-11-06T08:00:00Z", "allowed_ips": [ "203.0.113.10/32" ], "webhook_url": "https://bayi.example.com/webhooks/mas4games" } } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/categories": { "get": { "operationId": "categories", "tags": [ "Catalog" ], "summary": "List categories", "description": "Returns the categories open to you. Sub-categories point to their parent with `parent_id`.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "id": 3, "slug": "pubg-mobile", "name": "PUBG Mobile", "parent_id": null, "image_url": "https://www.mas4games.com/uploads/catalog/pubg.webp" }, { "id": 5, "slug": "google-play", "name": "Google Play", "parent_id": null, "image_url": "https://www.mas4games.com/uploads/catalog/google-play.webp" } ], "has_more": false, "next_cursor": null } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products": { "get": { "operationId": "products", "tags": [ "Catalog" ], "summary": "List products", "description": "Returns the products open to you at your own prices, ordered by product id. With `updated_since` you get only those whose price, stock or availability changed (changes are processed every five minutes).", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Records per page, 1–200 (default 50)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous answer's `next_cursor`", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "required": false, "description": "Only this category's products (and its sub-categories')", "schema": { "type": "integer" } }, { "name": "ids", "in": "query", "required": false, "description": "Comma-separated product ids (at most 200)", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only those changed after this time (ISO-8601)", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "object": "product", "id": 241, "sku": "pubg-mobile-660-uc", "name": "PUBG Mobile 660 UC", "names": { "tr": "PUBG Mobile 660 UC", "en": "PUBG Mobile 660 UC", "ar": "PUBG Mobile 660 UC" }, "category": { "id": 3, "name": "PUBG Mobile" }, "type": "topup", "region": "global", "price": { "amount": 41990, "currency": "TRY" }, "list_price": { "amount": 44990, "currency": "TRY" }, "available": true, "stock": null, "min_quantity": 1, "max_quantity": 10, "sale_hours": null, "fields": [ { "key": "playerId", "labels": { "tr": "Oyuncu ID", "en": "Player ID", "ar": "معرّف اللاعب" }, "type": "digits", "required": true, "min_length": 5, "max_length": 64, "options": null } ], "image_url": "https://www.mas4games.com/uploads/catalog/pubg.webp", "description": null, "updated_at": "2026-11-06T07:55:00Z" } ], "has_more": true, "next_cursor": "MjQx" } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited, parameter_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/products/{id}": { "get": { "operationId": "product", "tags": [ "Catalog" ], "summary": "Retrieve a product", "description": "Returns one product. Check its price and availability here before high-value orders.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The product's id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "object": "product", "id": 241, "sku": "pubg-mobile-660-uc", "name": "PUBG Mobile 660 UC", "names": { "tr": "PUBG Mobile 660 UC", "en": "PUBG Mobile 660 UC", "ar": "PUBG Mobile 660 UC" }, "category": { "id": 3, "name": "PUBG Mobile" }, "type": "topup", "region": "global", "price": { "amount": 41990, "currency": "TRY" }, "list_price": { "amount": 44990, "currency": "TRY" }, "available": true, "stock": null, "min_quantity": 1, "max_quantity": 10, "sale_hours": null, "fields": [ { "key": "playerId", "labels": { "tr": "Oyuncu ID", "en": "Player ID", "ar": "معرّف اللاعب" }, "type": "digits", "required": true, "min_length": 5, "max_length": 64, "options": null } ], "image_url": "https://www.mas4games.com/uploads/catalog/pubg.webp", "description": null, "updated_at": "2026-11-06T07:55:00Z" } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited, product_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders": { "post": { "operationId": "createOrder", "tags": [ "Orders" ], "summary": "Create an order", "description": "Pays the order from your balance at once and starts delivery; returns the order with 201. If a line can't be ordered, no order is made and the error names the line in param. A test key places at most 500 test orders in 24 hours (429 `rate_limited` with `Retry-After`).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique value for this operation (1–255 characters); the same one on a retry", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "object": "order", "id": "M4G105146", "reference": "SIP-10045", "mode": "live", "source": "api", "status": "processing", "currency": "TRY", "total": { "amount": 61990, "currency": "TRY" }, "refunded": { "amount": 0, "currency": "TRY" }, "created_at": "2026-11-06T08:12:40Z", "items": [ { "id": 5614, "product_id": 241, "product_name": "PUBG Mobile 660 UC", "quantity": 1, "unit_price": { "amount": 41990, "currency": "TRY" }, "amount": { "amount": 41990, "currency": "TRY" }, "gift": false, "status": "processing", "fields": { "playerId": "5123456789" }, "codes": null, "codes_count": 0, "delivery_note": null, "delivered_at": null, "cancel_reason": null }, { "id": 5615, "product_id": 77, "product_name": "Xbox 100 TL Hediye Kartı", "quantity": 2, "unit_price": { "amount": 10000, "currency": "TRY" }, "amount": { "amount": 20000, "currency": "TRY" }, "gift": false, "status": "delivered", "fields": {}, "codes": null, "codes_count": 2, "delivery_note": null, "delivered_at": "2026-11-06T08:12:41Z", "cancel_reason": null } ] } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited, invalid_json, parameter_missing, parameter_invalid, field_unknown, field_invalid, product_not_found, product_unavailable, out_of_stock, quantity_out_of_range, outside_sale_hours, daily_limit_reached, spending_limit_reached, insufficient_balance, account_restricted, email_unverified, billing_details_required, balance_payment_unavailable, duplicate_reference, idempotency_key_reused, request_in_progress, order_failed, maintenance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listOrders", "tags": [ "Orders" ], "summary": "List orders", "description": "Returns your orders, newest first (orders placed on the site come too, with source: store). Codes are not in the list.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Records per page, 1–200 (default 50)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous answer's `next_cursor`", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "processing, completed, `partially_completed` or cancelled", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "required": false, "description": "The order placed with this reference", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "required": false, "description": "Created at or after this time", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "required": false, "description": "Created before this time", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "object": "order", "id": "M4G105146", "reference": "SIP-10045", "status": "completed", "…": "…" } ], "has_more": false, "next_cursor": null } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited, parameter_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "tags": [ "Orders" ], "summary": "Retrieve an order", "description": "Returns the order with the codes of its delivered lines. Without webhooks, follow delivery with this endpoint.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's id (M4G…; TST… in the sandbox)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "object": "order", "id": "M4G105146", "reference": "SIP-10045", "mode": "live", "source": "api", "status": "completed", "currency": "TRY", "total": { "amount": 61990, "currency": "TRY" }, "refunded": { "amount": 0, "currency": "TRY" }, "created_at": "2026-11-06T08:12:40Z", "items": [ { "id": 5614, "product_id": 241, "product_name": "PUBG Mobile 660 UC", "quantity": 1, "unit_price": { "amount": 41990, "currency": "TRY" }, "amount": { "amount": 41990, "currency": "TRY" }, "gift": false, "status": "delivered", "fields": { "playerId": "5123456789" }, "codes": [], "codes_count": 0, "delivery_note": "L8RZvemd2K2d39qfS7", "delivered_at": "2026-11-06T08:13:05Z", "cancel_reason": null }, { "id": 5615, "product_id": 77, "product_name": "Xbox 100 TL Hediye Kartı", "quantity": 2, "unit_price": { "amount": 10000, "currency": "TRY" }, "amount": { "amount": 20000, "currency": "TRY" }, "gift": false, "status": "delivered", "fields": {}, "codes": [ "XB1A-7KQ2-PL9D-3M2X", "XB1A-8LR3-QM0E-4N3Y" ], "codes_count": 2, "delivery_note": null, "delivered_at": "2026-11-06T08:12:41Z", "cancel_reason": null } ] } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited, order_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/cancel": { "post": { "operationId": "cancelOrder", "tags": [ "Orders" ], "summary": "Cancel an order", "description": "Cancels lines not delivered yet and refunds their amounts to your balance at once. Without items, every cancellable line is cancelled. An order whose lines go together (a coupon on the order, a bundle, a buy-together price, a free gift line or the line that earned it) is cancelled whole or not at all: leave items out (or list all of its lines); naming only some of them, or having any of its lines delivered or being bought from a supplier, is 409 `order_not_cancellable` with a message saying why. Orders held for payment review or handled by our staff are never cancelled through the API: contact support. Other orders keep the per-line cancel. Only orders paid from your balance (every API order is) can be cancelled.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique value for this operation (1–255 characters); the same one on a retry", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The order's id (M4G…; TST… in the sandbox)", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCancel" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "object": "order", "id": "M4G105146", "status": "partially_completed", "refunded": { "amount": 41990, "currency": "TRY" }, "items": [ { "id": 5614, "status": "cancelled", "cancel_reason": "Customer changed their mind", "…": "…" }, { "id": 5615, "status": "delivered", "…": "…" } ] } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited, invalid_json, parameter_invalid, order_not_found, item_not_found, order_not_cancellable, idempotency_key_reused, request_in_progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/balance/transactions": { "get": { "operationId": "transactions", "tags": [ "Balance" ], "summary": "Balance transactions", "description": "Returns your balance's movements (purchases, refunds, top-ups), newest first, for reconciliation. With a test key the list is always empty: the sandbox moves no money.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Records per page, 1–200 (default 50)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous answer's `next_cursor`", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "Currency (default: your key's currency)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceTransaction" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "object": "list", "data": [ { "object": "balance_transaction", "id": 90211, "type": "purchase", "amount": { "amount": -61990, "currency": "TRY" }, "balance_after": { "amount": 1183085, "currency": "TRY" }, "order_id": "M4G105146", "created_at": "2026-11-06T08:12:40Z" } ], "has_more": true, "next_cursor": "OTAyMTE" } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited, parameter_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook": { "get": { "operationId": "getWebhook", "tags": [ "Webhook endpoint" ], "summary": "Retrieve the webhook endpoint", "description": "Returns the webhook address set and the last characters of your signing secret.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "url": "https://bayi.example.com/webhooks/mas4games", "secret_hint": "whsec_…Q3xZ", "events": [ "order.item.delivered", "order.item.cancelled", "product.updated", "ping" ] } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setWebhook", "tags": [ "Webhook endpoint" ], "summary": "Set the webhook endpoint", "description": "Sets the https address events are sent to; null stops webhooks. A new address is sent to at once, even when the old one was paused after failures.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSet" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "url": "https://bayi.example.com/webhooks/mas4games", "secret_hint": "whsec_…Q3xZ", "events": [ "order.item.delivered", "order.item.cancelled", "product.updated", "ping" ] } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited, invalid_json, parameter_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook/test": { "post": { "operationId": "testWebhook", "tags": [ "Webhook endpoint" ], "summary": "Send a test event", "description": "Sends a signed ping event to your address and tells you the result; use it while building your receiver. A successful test also resumes at once an address paused after failures. At most 30 an hour per key: beyond that 429 `rate_limited` with `Retry-After`.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTest" }, "example": { "object": "webhook_test", "event_id": "evt_5d4c3b2a1f0e9d8c7b6a5f4e", "delivered": true, "response_status": 200, "error": null } } } }, "429": { "description": "Too many requests: 120 a minute per key, 30 webhook tests an hour, or 500 orders in 24 hours with a test key. With each of them, `Retry-After` gives the seconds to wait.", "headers": { "Retry-After": { "description": "Seconds to wait before trying again", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Something went wrong on our side; write to support with the `request_id`. When you retry an order, send the same `Idempotency-Key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Error: invalid_api_key, rate_limited, webhook_not_set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "order.item.delivered": { "post": { "summary": "An order line was delivered; `data.order` is the whole order with codes, `data.item_id` the line.", "parameters": [ { "name": "Mas4games-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Every request has a `Mas4games-Signature` header: `t=1793952765,v1=5f0b3c…`. v1 is the HMAC-SHA256, with your whsec_ secret, of the raw body prefixed with the time and a dot (`t.body`)." }, { "name": "Mas4games-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Mas4games-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledge an event with 2xx within 8 seconds and do the work afterwards: a call that takes longer counts as failed, and the body of your answer is ignored. Any other answer is tried again after 1, 5 and 15 minutes, then hourly and every six hours (at most 12 times)." } } } }, "order.item.cancelled": { "post": { "summary": "An order line was cancelled and its amount went back to your balance.", "parameters": [ { "name": "Mas4games-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Every request has a `Mas4games-Signature` header: `t=1793952765,v1=5f0b3c…`. v1 is the HMAC-SHA256, with your whsec_ secret, of the raw body prefixed with the time and a dot (`t.body`)." }, { "name": "Mas4games-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Mas4games-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledge an event with 2xx within 8 seconds and do the work afterwards: a call that takes longer counts as failed, and the body of your answer is ignored. Any other answer is tried again after 1, 5 and 15 minutes, then hourly and every six hours (at most 12 times)." } } } }, "product.updated": { "post": { "summary": "Products whose price, stock or availability changed (every five minutes, up to 100 at a time); a product taken off sale comes with `status: removed`.", "parameters": [ { "name": "Mas4games-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Every request has a `Mas4games-Signature` header: `t=1793952765,v1=5f0b3c…`. v1 is the HMAC-SHA256, with your whsec_ secret, of the raw body prefixed with the time and a dot (`t.body`)." }, { "name": "Mas4games-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Mas4games-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledge an event with 2xx within 8 seconds and do the work afterwards: a call that takes longer counts as failed, and the body of your answer is ignored. Any other answer is tried again after 1, 5 and 15 minutes, then hourly and every six hours (at most 12 times)." } } } }, "ping": { "post": { "summary": "The test event sent by `POST /webhook/test`.", "parameters": [ { "name": "Mas4games-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Every request has a `Mas4games-Signature` header: `t=1793952765,v1=5f0b3c…`. v1 is the HMAC-SHA256, with your whsec_ secret, of the raw body prefixed with the time and a dot (`t.body`)." }, { "name": "Mas4games-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Mas4games-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledge an event with 2xx within 8 seconds and do the work afterwards: a call that takes longer counts as failed, and the body of your answer is ignored. Any other answer is tried again after 1, 5 and 15 minutes, then hourly and every six hours (at most 12 times)." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A key's start tells its environment: `m4gc_live_` real orders, `m4gc_test_` the sandbox. The two environments' orders are kept apart." } }, "schemas": { "Money": { "type": "object", "description": "An amount in the currency's smallest unit (kuruş, cents): 41990 TRY is 419.90 TL.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "integer" }, "currency": { "type": "string", "example": "TRY" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string" }, "code": { "type": "string", "enum": [ "invalid_api_key", "rate_limited", "route_not_found", "invalid_json", "body_too_large", "parameter_missing", "parameter_invalid", "field_unknown", "field_invalid", "product_not_found", "product_unavailable", "out_of_stock", "quantity_out_of_range", "outside_sale_hours", "daily_limit_reached", "spending_limit_reached", "insufficient_balance", "account_restricted", "email_unverified", "billing_details_required", "balance_payment_unavailable", "duplicate_reference", "idempotency_key_reused", "request_in_progress", "order_not_found", "item_not_found", "order_not_cancellable", "webhook_not_set", "order_failed", "maintenance", "service_unavailable", "internal_error" ] }, "message": { "type": "string" }, "param": { "type": "string", "description": "The parameter or field at fault, e.g. items[0].fields.playerId" }, "order_id": { "type": "string", "description": "With duplicate_reference: the order already made with this reference." }, "request_id": { "type": [ "string", "null" ] } } } } }, "Account": { "type": "object", "properties": { "object": { "const": "account" }, "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "customer_type": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "currency_decimals": { "type": "integer" }, "balances": { "type": "array", "description": "With a test key: one made-up sandbox balance of 1000000 in the key's currency, which never changes.", "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" }, "decimals": { "type": "integer" } } } }, "key": { "type": "object", "properties": { "mode": { "enum": [ "live", "test" ] }, "created_at": { "type": "string", "format": "date-time" }, "allowed_ips": { "type": "array", "items": { "type": "string" } }, "webhook_url": { "type": [ "string", "null" ], "description": "Cleared when the key is renewed: set it again with the new key." } } } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "type": [ "integer", "null" ] }, "image_url": { "type": [ "string", "null" ] } } }, "ProductField": { "type": "object", "properties": { "key": { "type": "string", "example": "playerId" }, "labels": { "type": "object", "properties": { "tr": { "type": "string" }, "en": { "type": "string" }, "ar": { "type": "string" } } }, "type": { "enum": [ "digits", "text", "select" ] }, "required": { "type": "boolean" }, "min_length": { "type": [ "integer", "null" ] }, "max_length": { "type": [ "integer", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "Product": { "type": "object", "properties": { "object": { "const": "product" }, "id": { "type": "integer" }, "sku": { "type": "string" }, "name": { "type": "string" }, "names": { "type": "object", "properties": { "tr": { "type": "string" }, "en": { "type": "string" }, "ar": { "type": "string" } } }, "category": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "type": { "enum": [ "code", "topup" ], "description": "code: delivered as codes; topup: loaded to the player's account (see fields)." }, "region": { "type": [ "string", "null" ] }, "price": { "$ref": "#/components/schemas/Money" }, "list_price": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "available": { "type": "boolean", "description": "Whether an order is accepted now." }, "stock": { "type": [ "integer", "null" ], "description": "null: no stock limit." }, "min_quantity": { "type": "integer" }, "max_quantity": { "type": "integer" }, "sale_hours": { "oneOf": [ { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "time_zone": { "type": "string" } } }, { "type": "null" } ] }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ProductField" } }, "image_url": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "const": "removed", "description": "Only in product.updated, for a product taken off sale." } } }, "OrderItem": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": [ "integer", "null" ] }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "$ref": "#/components/schemas/Money" }, "amount": { "$ref": "#/components/schemas/Money" }, "gift": { "type": "boolean" }, "status": { "enum": [ "awaiting_payment", "processing", "delivered", "cancelled" ] }, "fields": { "type": "object", "additionalProperties": { "type": "string" } }, "codes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Only in GET /orders/{id} and webhooks; null elsewhere." }, "codes_count": { "type": "integer" }, "delivery_note": { "type": [ "string", "null" ], "description": "What the delivery tells besides codes, once the line is delivered: a top-up by ID's transaction number, say (TEST-TX-… in the sandbox); null when there is none." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancel_reason": { "type": [ "string", "null" ] } } }, "Order": { "type": "object", "properties": { "object": { "const": "order" }, "id": { "type": "string", "example": "M4G105146" }, "reference": { "type": [ "string", "null" ] }, "mode": { "enum": [ "live", "test" ] }, "source": { "enum": [ "api", "store" ] }, "status": { "enum": [ "processing", "completed", "partially_completed", "cancelled" ] }, "currency": { "type": "string" }, "total": { "$ref": "#/components/schemas/Money" }, "refunded": { "$ref": "#/components/schemas/Money" }, "created_at": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } } } }, "OrderCreate": { "type": "object", "required": [ "items" ], "properties": { "reference": { "type": "string", "maxLength": 100 }, "items": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }, "fields": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "OrderCancel": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "integer" } }, "reason": { "type": "string", "maxLength": 200 } } }, "BalanceTransaction": { "type": "object", "properties": { "object": { "const": "balance_transaction" }, "id": { "type": "integer" }, "type": { "type": "string", "example": "purchase" }, "amount": { "$ref": "#/components/schemas/Money" }, "balance_after": { "$ref": "#/components/schemas/Money" }, "order_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookEndpoint": { "type": "object", "properties": { "object": { "const": "webhook_endpoint" }, "url": { "type": [ "string", "null" ] }, "secret_hint": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } } } }, "WebhookSet": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": [ "string", "null" ], "maxLength": 300 } } }, "WebhookTest": { "type": "object", "properties": { "object": { "const": "webhook_test" }, "event_id": { "type": "string" }, "delivered": { "type": "boolean" }, "response_status": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } } }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "event" }, "type": { "enum": [ "order.item.delivered", "order.item.cancelled", "product.updated", "ping" ] }, "mode": { "enum": [ "live", "test" ] }, "api_version": { "const": "v1" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } } } } }