{
  "swagger": "2.0",
  "info": {
    "description": "Payments API v2 (beta): user API key xapi_, the cashbox is named by device_name. Sandbox: test key xapi_test_ and the test cashbox device_name \"test\". Merchant API of subscriptions: subscription project key xsub_.",
    "title": "xPayment API v2 (beta)",
    "contact": {},
    "version": "2.0"
  },
  "basePath": "/v2",
  "paths": {
    "/devices": {
      "get": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "description": "The caller's active cashboxes that have a device_name — the names POST /payments and POST /payments/link take — with the health of their Kaspi session: session_problem_since is when Kaspi stopped accepting the cashbox's session, null while it works. Read-only.\nWith a test key (xapi_test_…) the list is the sandbox's test cashbox, device_name \"test\".",
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-payments"
        ],
        "summary": "List your cashboxes",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.deviceV2ListResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments": {
      "get": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-payments"
        ],
        "summary": "List payments",
        "parameters": [
          {
            "type": "string",
            "description": "Filter by status, uppercase as returned (PENDING, COMPLETED, CANCELLED, EXPIRED, FAILED, …)",
            "name": "status",
            "in": "query"
          },
          {
            "type": "string",
            "description": "Filter by payer phone",
            "name": "payer_phone",
            "in": "query"
          },
          {
            "type": "string",
            "description": "Filter by merchant order ID",
            "name": "merchant_order_id",
            "in": "query"
          },
          {
            "type": "string",
            "description": "Filter by device_name (case-insensitive; includes payments of earlier devices with this name)",
            "name": "device_name",
            "in": "query"
          },
          {
            "type": "string",
            "description": "Pagination cursor",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.paymentListResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "description": "Initiates a Kaspi QR payment on the caller's active device with this device_name (case-insensitive).",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-payments"
        ],
        "summary": "Create a payment",
        "parameters": [
          {
            "type": "string",
            "description": "Idempotency key",
            "name": "X-Idempotency-Key",
            "in": "header"
          },
          {
            "description": "Payment request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.createPaymentV2Request"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.paymentObject"
            }
          },
          "400": {
            "description": "VALIDATION_ERROR — device_name missing or not Latin letters/digits",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "DEVICE_NOT_FOUND — no active device of yours has this device_name",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "IDEMPOTENCY_CONFLICT — the X-Idempotency-Key is already on another payment of the same owner",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "422": {
            "description": "Unprocessable Entity",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "429": {
            "description": "RATE_LIMITED — a test key's sandbox writes: 60 a minute, 1000 a day per user",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments/{paymentID}": {
      "get": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-payments"
        ],
        "summary": "Get a payment",
        "parameters": [
          {
            "type": "string",
            "description": "Payment ID",
            "name": "paymentID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.paymentObject"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments/{paymentID}/cancel": {
      "post": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-payments"
        ],
        "summary": "Cancel a payment",
        "parameters": [
          {
            "type": "string",
            "description": "Payment ID",
            "name": "paymentID",
            "in": "path",
            "required": true
          },
          {
            "description": "Cancel reason",
            "name": "body",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/handler.cancelPaymentRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.paymentObject"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "Conflict",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments/{paymentID}/refund": {
      "post": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-refunds"
        ],
        "summary": "Refund a payment",
        "parameters": [
          {
            "type": "string",
            "description": "Payment ID",
            "name": "paymentID",
            "in": "path",
            "required": true
          },
          {
            "description": "Refund request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.createRefundRequest"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Accepted",
            "schema": {
              "$ref": "#/definitions/handler.refundObject"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "Conflict",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "429": {
            "description": "RATE_LIMITED — a test key's sandbox writes: 60 a minute, 1000 a day per user",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments/{paymentID}/refunds": {
      "get": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-refunds"
        ],
        "summary": "List refunds of a payment",
        "parameters": [
          {
            "type": "string",
            "description": "Payment ID",
            "name": "paymentID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.refundListResponse"
            }
          }
        }
      }
    },
    "/payments/link": {
      "post": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "description": "Generates a Kaspi QR payment link on the caller's active device with this device_name.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-payments"
        ],
        "summary": "Create a payment link",
        "parameters": [
          {
            "description": "Payment link request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.createPaymentLinkV2Request"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.paymentLinkResponse"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "DEVICE_NOT_FOUND",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "422": {
            "description": "Unprocessable Entity",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "429": {
            "description": "RATE_LIMITED — a test key's sandbox writes: 60 a minute, 1000 a day per user",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/refunds": {
      "get": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-refunds"
        ],
        "summary": "List refunds",
        "parameters": [
          {
            "type": "string",
            "description": "Filter by payment",
            "name": "payment_id",
            "in": "query"
          },
          {
            "type": "string",
            "description": "Filter by status (PENDING, PROCESSING, COMPLETED, FAILED)",
            "name": "status",
            "in": "query"
          },
          {
            "type": "string",
            "description": "Pagination cursor",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.refundListResponse"
            }
          }
        }
      }
    },
    "/refunds/{refundID}": {
      "get": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-refunds"
        ],
        "summary": "Get a refund",
        "parameters": [
          {
            "type": "string",
            "description": "Refund ID",
            "name": "refundID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.refundObject"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/sandbox/payments/{paymentID}/simulate": {
      "post": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "description": "Sandbox only: needs a test key (xapi_test_…); a live key gets 403 SANDBOX_ONLY. Ends an unfinished test payment (PENDING, WAITING_FOR_PAYER, QR_TOKEN_CREATED) at once, as Kaspi would: paid → COMPLETED (payment.completed), declined → CANCELLED (payment.cancelled), expired → EXPIRED (payment.expired), failed → FAILED (payment.failed). The webhook goes to your test subscriptions. A payment takes one outcome; any later call answers 409 SANDBOX_OUTCOME_NOT_ALLOWED.\nLimited with the other sandbox writes (creating a payment, a link, a refund): 60 a minute and 1000 a day per user, then 429 RATE_LIMITED with Retry-After.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-sandbox"
        ],
        "summary": "Simulate the outcome of a test payment",
        "parameters": [
          {
            "type": "string",
            "description": "Payment ID",
            "name": "paymentID",
            "in": "path",
            "required": true
          },
          {
            "description": "Outcome",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.simulateRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.paymentObject"
            }
          },
          "400": {
            "description": "VALIDATION_ERROR — outcome is not one of paid, declined, expired, failed",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "SANDBOX_ONLY — a live key",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "PAYMENT_NOT_FOUND — not a test payment of yours",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "SANDBOX_OUTCOME_NOT_ALLOWED — the payment is no longer unfinished or has its outcome",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "429": {
            "description": "RATE_LIMITED",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/static-qr-payments/{orderNumber}": {
      "get": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "description": "Not in the sandbox: a test key (xapi_test_…) gets 404 NOT_AVAILABLE_IN_SANDBOX.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-static-qr"
        ],
        "summary": "Get a static QR payment by order number",
        "parameters": [
          {
            "type": "string",
            "description": "Order number",
            "name": "orderNumber",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.staticQrPaymentObject"
            }
          },
          "404": {
            "description": "NOT_FOUND, or NOT_AVAILABLE_IN_SANDBOX for a test key",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/subscriptions/accounts/{externalID}": {
      "get": {
        "security": [
          {
            "SubscriptionKeyAuth": []
          }
        ],
        "description": "Status (none, trial, active, canceling, expired), access, the period and its end (until — the last day in Kazakhstan; access_ends_at — the moment access ends, RFC3339 UTC), plans and add-ons; with access also the capabilities (with their source) and the limits (limit — the code, limit_value — the number, null when unlimited; used and remaining in the current period; resets_at). Cache the answer for at most a minute.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-subscriptions"
        ],
        "summary": "Get the entitlements of an account",
        "parameters": [
          {
            "type": "string",
            "description": "The account's id in your service (URL-encoded)",
            "name": "externalID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.subAPIEntitlementsObject"
            }
          },
          "400": {
            "description": "VALIDATION_ERROR (external_id)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "ACCOUNT_NOT_FOUND",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "429": {
            "description": "RATE_LIMITED",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "put": {
        "security": [
          {
            "SubscriptionKeyAuth": []
          }
        ],
        "description": "Creates the account with this external id (201, created_via api) or updates it (200). Every field is optional: absent — unchanged, null — cleared. The phone is normalized to +7XXXXXXXXXX. The external id is URL-encoded in the path (user%40mail.kz) and must be 1–100 characters of A–Z a–z 0–9 . _ : @ + -. The answer is the account's entitlements.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-subscriptions"
        ],
        "summary": "Create or update an account",
        "parameters": [
          {
            "type": "string",
            "description": "The account's id in your service (URL-encoded)",
            "name": "externalID",
            "in": "path",
            "required": true
          },
          {
            "description": "Account fields",
            "name": "body",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/handler.subAPIAccountRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated",
            "schema": {
              "$ref": "#/definitions/handler.subAPIEntitlementsObject"
            }
          },
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.subAPIEntitlementsObject"
            }
          },
          "400": {
            "description": "VALIDATION_ERROR (external_id, name, phone, email)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "PHONE_REQUIRED, SUBSCRIPTION_BUSY",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "422": {
            "description": "ACCOUNT_LIMIT",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "429": {
            "description": "RATE_LIMITED",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/subscriptions/accounts/{externalID}/check": {
      "get": {
        "security": [
          {
            "SubscriptionKeyAuth": []
          }
        ],
        "description": "Exactly one of capability or limit (a code); need (1…10^9, default 1) only with limit. Order: 400 → 404 UNKNOWN_CODE → always 200, an unknown account included (allowed false, reason account_not_found, status none). reason when not allowed: account_not_found, no_subscription, expired, not_in_plan, limit_not_set, limit_exhausted (remaining < need). A limit check also answers limit (the code), limit_value (null when unlimited), unlimited, used, remaining, resets_at; its source is null.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-subscriptions"
        ],
        "summary": "Check one capability or limit",
        "parameters": [
          {
            "type": "string",
            "description": "The account's id in your service (URL-encoded)",
            "name": "externalID",
            "in": "path",
            "required": true
          },
          {
            "type": "string",
            "description": "Capability code",
            "name": "capability",
            "in": "query"
          },
          {
            "type": "string",
            "description": "Limit code",
            "name": "limit",
            "in": "query"
          },
          {
            "type": "integer",
            "description": "Amount a limit check asks for (default 1)",
            "name": "need",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.subCheckResultObject"
            }
          },
          "400": {
            "description": "VALIDATION_ERROR (external_id, capability, need)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "UNKNOWN_CODE",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "429": {
            "description": "RATE_LIMITED",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/subscriptions/accounts/{externalID}/trial": {
      "post": {
        "security": [
          {
            "SubscriptionKeyAuth": []
          }
        ],
        "description": "Starts a trial of the plans and add-ons (codes) for an account without access (create it first with PUT). The trial lasts the longest trial of the plans; period (month or year, default month) is the period after it. The composition rules: in mode blocks one plan per block and a plan in every required block that sells one, in mode simple exactly one plan; plans must be active, add-ons not withdrawn.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-subscriptions"
        ],
        "summary": "Start a trial",
        "parameters": [
          {
            "type": "string",
            "description": "The account's id in your service (URL-encoded)",
            "name": "externalID",
            "in": "path",
            "required": true
          },
          {
            "description": "Plans and add-ons",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.subAPITrialRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.subAPIEntitlementsObject"
            }
          },
          "400": {
            "description": "VALIDATION_ERROR (external_id, plans, addons, period)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "UNKNOWN_CODE, ACCOUNT_NOT_FOUND",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "TRIAL_NOT_ALLOWED, TRIAL_ALREADY_USED, NO_TRIAL, SUBSCRIPTION_BUSY",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "429": {
            "description": "RATE_LIMITED",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/subscriptions/accounts/{externalID}/usage": {
      "post": {
        "security": [
          {
            "SubscriptionKeyAuth": []
          }
        ],
        "description": "Adds delta (a non-zero integer within ±10^9; negative — e.g. a product deleted, the counter never goes below 0) to the account's counter of the limit in the current period (reset day/month by the Kazakhstan calendar). The X-Idempotency-Key header (1–100 visible ASCII characters) is required: a repeat with the same key and body gets the stored answer (200 or 409) and counts nothing; the same key with another body is 422. A positive delta needs access (409 NO_ACCESS); a negative one is accepted without it. A delta that would take a finite limit over is refused whole: 409 LIMIT_EXCEEDED with the current values, nothing counted.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-subscriptions"
        ],
        "summary": "Report usage of a limit",
        "parameters": [
          {
            "type": "string",
            "description": "The account's id in your service (URL-encoded)",
            "name": "externalID",
            "in": "path",
            "required": true
          },
          {
            "type": "string",
            "description": "Idempotency key",
            "name": "X-Idempotency-Key",
            "in": "header",
            "required": true
          },
          {
            "description": "Usage",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.subAPIUsageRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.subAPIUsageObject"
            }
          },
          "400": {
            "description": "VALIDATION_ERROR (external_id, X-Idempotency-Key, limit, delta)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "UNKNOWN_CODE, ACCOUNT_NOT_FOUND",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "LIMIT_EXCEEDED (with the current values), NO_ACCESS, LIMIT_NOT_SET",
            "schema": {
              "$ref": "#/definitions/handler.subAPIUsageRefusalObject"
            }
          },
          "422": {
            "description": "IDEMPOTENCY_KEY_REUSED",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "429": {
            "description": "RATE_LIMITED",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/webhook-simulate": {
      "post": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "description": "With a test key (xapi_test_…), your own test subscriptions get the event, its body carrying \"environment\": \"sandbox\".",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-webhook-simulate"
        ],
        "summary": "Simulate a webhook event",
        "parameters": [
          {
            "description": "Event to simulate",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.simulateEventRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.simulateEventResponse"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/webhook-simulate/subscriptions": {
      "get": {
        "security": [
          {
            "APIKeyAuth": []
          }
        ],
        "description": "With a test key (xapi_test_…), your own test subscriptions instead of the organization's.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "v2-webhook-simulate"
        ],
        "summary": "List your webhook subscriptions",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.subscriptionListResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "domain.WebhookEventType": {
      "type": "string",
      "enum": [
        "payment.completed",
        "payment.expired",
        "payment.cancelled",
        "payment.failed",
        "payment.refunded",
        "payment.refund_failed",
        "booking.confirmed",
        "booking.expired",
        "booking.cancelled",
        "booking.rescheduled",
        "*"
      ],
      "x-enum-varnames": [
        "EventPaymentCompleted",
        "EventPaymentExpired",
        "EventPaymentCancelled",
        "EventPaymentFailed",
        "EventPaymentRefunded",
        "EventPaymentRefundFailed",
        "EventBookingConfirmed",
        "EventBookingExpired",
        "EventBookingCancelled",
        "EventBookingRescheduled",
        "EventAll"
      ]
    },
    "handler.cancelPaymentRequest": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "example": "Customer requested cancellation"
        }
      }
    },
    "handler.createPaymentLinkV2Request": {
      "type": "object",
      "required": [
        "amount",
        "device_name"
      ],
      "properties": {
        "amount": {
          "type": "number",
          "example": 1500
        },
        "device_name": {
          "type": "string",
          "example": "Kassa1"
        },
        "merchant_order_id": {
          "type": "string",
          "example": "order-42"
        }
      }
    },
    "handler.createPaymentV2Request": {
      "type": "object",
      "required": [
        "amount",
        "device_name",
        "payer_phone"
      ],
      "properties": {
        "amount": {
          "type": "number",
          "example": 1500
        },
        "comment": {
          "type": "string",
          "example": "Order #42"
        },
        "device_name": {
          "type": "string",
          "example": "Kassa1"
        },
        "merchant_order_id": {
          "type": "string",
          "example": "order-42"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {}
        },
        "payer_phone": {
          "type": "string",
          "example": "+77001234567"
        }
      }
    },
    "handler.createRefundRequest": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "example": 500
        },
        "reason": {
          "type": "string",
          "example": "Product returned"
        }
      }
    },
    "handler.deviceV2ListResponse": {
      "type": "object",
      "properties": {
        "devices": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.deviceV2Object"
          }
        }
      }
    },
    "handler.deviceV2Object": {
      "type": "object",
      "properties": {
        "device_name": {
          "type": "string",
          "example": "Kassa1"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "name": {
          "type": "string",
          "example": "Касса на входе"
        },
        "session_problem_since": {
          "type": "string",
          "example": "2026-11-07T10:15:00+05:00"
        }
      }
    },
    "handler.errorResponse": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "example": "VALIDATION_ERROR"
        },
        "message": {
          "type": "string",
          "example": "payer_phone and amount are required"
        }
      }
    },
    "handler.paymentLinkResponse": {
      "type": "object",
      "properties": {
        "environment": {
          "description": "\"sandbox\" for a link made with a test key",
          "type": "string",
          "enum": [
            "live",
            "sandbox"
          ],
          "example": "live"
        },
        "expire_date": {
          "type": "string",
          "example": "2026-04-06T11:39:53.000+05:00"
        },
        "ext_tran_id": {
          "type": "string",
          "example": "QR14893934009"
        },
        "payment_id": {
          "type": "string",
          "example": "uuid"
        },
        "qr_operation_id": {
          "type": "integer",
          "example": 14893934009
        },
        "qr_token": {
          "type": "string",
          "example": "https://qr.kaspi.kz/55308082630746899169618031642188672381021"
        },
        "status": {
          "type": "string",
          "example": "QrTokenCreated"
        }
      }
    },
    "handler.paymentListResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.paymentObject"
          }
        },
        "has_more": {
          "type": "boolean",
          "example": false
        },
        "next_cursor": {
          "type": "string",
          "example": ""
        }
      }
    },
    "handler.paymentObject": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "example": 1500
        },
        "cancel_reason": {
          "type": "string"
        },
        "cancelled_at": {
          "type": "string"
        },
        "comment": {
          "type": "string",
          "example": "Order #42"
        },
        "completed_at": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "currency": {
          "type": "string",
          "example": "KZT"
        },
        "device_name": {
          "description": "device_name of the device at creation; null when it had none",
          "type": "string",
          "example": "Kassa1"
        },
        "environment": {
          "description": "\"sandbox\" for a payment made with a test key",
          "type": "string",
          "enum": [
            "live",
            "sandbox"
          ],
          "example": "live"
        },
        "merchant_order_id": {
          "type": "string",
          "example": "order-uuid"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {}
        },
        "payer_phone": {
          "type": "string",
          "example": "+77001234567"
        },
        "payment_id": {
          "type": "string",
          "example": "uuid"
        },
        "status": {
          "type": "string",
          "example": "pending"
        },
        "updated_at": {
          "type": "string"
        },
        "user_id": {
          "type": "string",
          "example": "uuid"
        }
      }
    },
    "handler.refundListResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.refundObject"
          }
        },
        "has_more": {
          "type": "boolean",
          "example": false
        },
        "next_cursor": {
          "type": "string",
          "example": ""
        }
      }
    },
    "handler.refundObject": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "example": 500
        },
        "completed_at": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "environment": {
          "description": "\"sandbox\" for a refund made with a test key",
          "type": "string",
          "enum": [
            "live",
            "sandbox"
          ],
          "example": "live"
        },
        "fail_reason": {
          "type": "string"
        },
        "payment_id": {
          "type": "string",
          "example": "uuid"
        },
        "reason": {
          "type": "string",
          "example": "Product returned"
        },
        "refund_id": {
          "type": "string",
          "example": "uuid"
        },
        "status": {
          "type": "string",
          "example": "PENDING"
        },
        "updated_at": {
          "type": "string"
        },
        "user_id": {
          "type": "string",
          "example": "uuid"
        }
      }
    },
    "handler.simulateEventRequest": {
      "type": "object",
      "properties": {
        "event": {
          "allOf": [
            {
              "$ref": "#/definitions/domain.WebhookEventType"
            }
          ],
          "example": "payment.completed"
        },
        "merchant_order_id": {
          "type": "string",
          "example": "order-123"
        },
        "subscription_id": {
          "type": "string",
          "example": "uuid"
        }
      }
    },
    "handler.simulateEventResponse": {
      "type": "object",
      "properties": {
        "results": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.simulateResult"
          }
        }
      }
    },
    "handler.simulateRequest": {
      "type": "object",
      "required": [
        "outcome"
      ],
      "properties": {
        "outcome": {
          "type": "string",
          "enum": [
            "paid",
            "declined",
            "expired",
            "failed"
          ],
          "example": "paid"
        }
      }
    },
    "handler.simulateResult": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "example": "connection refused"
        },
        "event": {
          "type": "string",
          "example": "payment.completed"
        },
        "subscription_id": {
          "type": "string",
          "example": "uuid"
        },
        "success": {
          "type": "boolean",
          "example": true
        },
        "url": {
          "type": "string",
          "example": "https://example.com/webhook"
        }
      }
    },
    "handler.staticQrPaymentObject": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "example": 12
        },
        "client_short_name": {
          "type": "string",
          "example": "Рустем Е."
        },
        "comment": {
          "type": "string",
          "example": "Order #45"
        },
        "features": {
          "type": "integer",
          "example": 0
        },
        "id": {
          "type": "integer",
          "example": 1
        },
        "kaspi_operation_id": {
          "type": "integer",
          "example": 15029656207
        },
        "operation_method": {
          "type": "integer",
          "example": 0
        },
        "operation_type": {
          "type": "integer",
          "example": 0
        },
        "order_number": {
          "type": "string",
          "example": "QR15029656207"
        },
        "order_reg_date": {
          "type": "string",
          "example": "2026-04-15T13:57:25+05:00"
        },
        "sale_id": {
          "type": "integer",
          "example": 14930989637
        },
        "sale_type": {
          "type": "string",
          "example": "Link"
        },
        "source_type": {
          "type": "string",
          "example": "GOLD"
        },
        "synced_at": {
          "type": "string",
          "example": "2026-04-15T14:00:00+05:00"
        }
      }
    },
    "handler.subAPIAccountRequest": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "example": "admin@kazmart.kz"
        },
        "name": {
          "type": "string",
          "example": "Kazmart.kz"
        },
        "phone": {
          "type": "string",
          "example": "+7 701 200 10 30"
        }
      }
    },
    "handler.subAPIAddonObject": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "example": "seat_extra"
        },
        "name": {
          "type": "string",
          "example": "Дополнительный сотрудник"
        }
      }
    },
    "handler.subAPICapabilityObject": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "example": "catalog"
        },
        "name": {
          "type": "string",
          "example": "Каталог товаров"
        },
        "source": {
          "$ref": "#/definitions/handler.subSourceObject"
        }
      }
    },
    "handler.subAPIEntitlementsObject": {
      "type": "object",
      "properties": {
        "access": {
          "type": "boolean",
          "example": true
        },
        "access_ends_at": {
          "type": "string",
          "example": "2026-11-01T19:00:00Z"
        },
        "addons": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.subAPIAddonObject"
          }
        },
        "awaiting_payment": {
          "type": "boolean",
          "example": false
        },
        "cancel_at_period_end": {
          "type": "boolean",
          "example": false
        },
        "capabilities": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.subAPICapabilityObject"
          }
        },
        "email": {
          "type": "string"
        },
        "external_id": {
          "type": "string",
          "example": "shop_1040"
        },
        "limits": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.subAPILimitObject"
          }
        },
        "name": {
          "type": "string",
          "example": "Kazmart.kz"
        },
        "period": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "example": "month"
        },
        "phone": {
          "type": "string",
          "example": "+77012001030"
        },
        "plans": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.subAPIPlanObject"
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "none",
            "trial",
            "active",
            "canceling",
            "expired"
          ],
          "example": "active"
        },
        "trial_end": {
          "type": "string"
        },
        "until": {
          "type": "string",
          "example": "2026-11-01"
        }
      }
    },
    "handler.subAPILimitObject": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "string",
          "example": "products"
        },
        "limit_value": {
          "type": "integer",
          "example": 500
        },
        "name": {
          "type": "string",
          "example": "Товары"
        },
        "remaining": {
          "type": "integer",
          "example": 290
        },
        "reset": {
          "type": "string",
          "enum": [
            "none",
            "day",
            "month"
          ],
          "example": "none"
        },
        "resets_at": {
          "type": "string",
          "example": "2026-10-31T19:00:00Z"
        },
        "unit": {
          "type": "string",
          "example": "шт"
        },
        "unlimited": {
          "type": "boolean",
          "example": false
        },
        "used": {
          "type": "integer",
          "example": 210
        }
      }
    },
    "handler.subAPIPlanObject": {
      "type": "object",
      "properties": {
        "block": {
          "type": "string",
          "example": "Каталог"
        },
        "code": {
          "type": "string",
          "example": "cat_start"
        },
        "name": {
          "type": "string",
          "example": "Старт"
        }
      }
    },
    "handler.subAPITrialRequest": {
      "type": "object",
      "properties": {
        "addons": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "period": {
          "type": "string",
          "enum": [
            "month",
            "year"
          ],
          "example": "month"
        },
        "plans": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "cat_start",
            "ord_basic"
          ]
        }
      }
    },
    "handler.subAPIUsageObject": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "string",
          "example": "orders_m"
        },
        "limit_value": {
          "type": "integer",
          "example": 300
        },
        "remaining": {
          "type": "integer",
          "example": 179
        },
        "resets_at": {
          "type": "string",
          "example": "2026-10-31T19:00:00Z"
        },
        "unlimited": {
          "type": "boolean",
          "example": false
        },
        "used": {
          "type": "integer",
          "example": 121
        }
      }
    },
    "handler.subAPIUsageRefusalObject": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "LIMIT_EXCEEDED",
            "NO_ACCESS",
            "LIMIT_NOT_SET"
          ],
          "example": "LIMIT_EXCEEDED"
        },
        "limit": {
          "type": "string",
          "example": "orders_m"
        },
        "limit_value": {
          "type": "integer",
          "example": 300
        },
        "message": {
          "type": "string",
          "example": "limit exceeded, nothing was counted"
        },
        "remaining": {
          "type": "integer",
          "example": 179
        },
        "resets_at": {
          "type": "string",
          "example": "2026-10-31T19:00:00Z"
        },
        "unlimited": {
          "type": "boolean",
          "example": false
        },
        "used": {
          "type": "integer",
          "example": 121
        }
      }
    },
    "handler.subAPIUsageRequest": {
      "type": "object",
      "properties": {
        "delta": {
          "type": "integer",
          "example": 1
        },
        "limit": {
          "type": "string",
          "example": "orders_m"
        }
      }
    },
    "handler.subCheckResultObject": {
      "type": "object",
      "properties": {
        "access_ends_at": {
          "type": "string",
          "example": "2026-11-13T19:00:00Z"
        },
        "allowed": {
          "type": "boolean",
          "example": true
        },
        "limit": {
          "type": "string",
          "example": "orders_m"
        },
        "limit_value": {
          "type": "integer",
          "example": 300
        },
        "reason": {
          "type": "string",
          "enum": [
            "account_not_found",
            "no_subscription",
            "expired",
            "not_in_plan",
            "limit_not_set",
            "limit_exhausted"
          ]
        },
        "remaining": {
          "type": "integer",
          "example": 0
        },
        "resets_at": {
          "type": "string",
          "example": "2026-10-31T19:00:00Z"
        },
        "source": {
          "$ref": "#/definitions/handler.subSourceObject"
        },
        "status": {
          "type": "string",
          "enum": [
            "none",
            "trial",
            "active",
            "canceling",
            "expired"
          ],
          "example": "canceling"
        },
        "unlimited": {
          "type": "boolean",
          "example": false
        },
        "until": {
          "type": "string",
          "example": "2026-11-13"
        },
        "used": {
          "type": "integer",
          "example": 300
        }
      }
    },
    "handler.subscriptionListResponse": {
      "type": "object",
      "properties": {
        "subscriptions": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.subscriptionObject"
          }
        }
      }
    },
    "handler.subscriptionObject": {
      "type": "object",
      "properties": {
        "created_at": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "failing_since": {
          "description": "FailingSince is set while a delivery has failed after every attempt and none has succeeded since; null otherwise.",
          "type": "string",
          "example": "2026-10-21T09:05:00Z"
        },
        "failure_count": {
          "description": "FailureCount counts the failed delivery attempts since the last success.",
          "type": "integer",
          "example": 0
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "last_failure_at": {
          "type": "string",
          "example": "2026-10-21T09:05:00Z"
        },
        "last_success_at": {
          "description": "LastSuccessAt / LastFailureAt are the last delivery attempt that succeeded / failed; null when none.",
          "type": "string",
          "example": "2026-10-21T09:00:00Z"
        },
        "organization_id": {
          "type": "string",
          "example": "uuid"
        },
        "secret": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "example": "https://example.com/webhook"
        }
      }
    },
    "handler.subSourceObject": {
      "type": "object",
      "properties": {
        "block": {
          "type": "string",
          "example": "Каталог"
        },
        "code": {
          "type": "string",
          "example": "cat_start"
        },
        "name": {
          "type": "string",
          "example": "Старт"
        },
        "type": {
          "type": "string",
          "enum": [
            "plan",
            "addon"
          ],
          "example": "plan"
        }
      }
    }
  },
  "securityDefinitions": {
    "APIKeyAuth": {
      "description": "User API key: \"Bearer xapi_…\", or a sandbox test key \"Bearer xapi_test_…\"",
      "type": "apiKey",
      "name": "Authorization",
      "in": "header"
    },
    "SubscriptionKeyAuth": {
      "description": "Subscription project key: \"Bearer xsub_…\" (the merchant API of subscriptions, /v2/subscriptions)",
      "type": "apiKey",
      "name": "Authorization",
      "in": "header"
    }
  },
  "host": "api.xpayment.kz",
  "schemes": [
    "https"
  ]
}
