{
  "swagger": "2.0",
  "info": {
    "contact": {},
    "title": "xPayment Partner API",
    "description": "Filtered OpenAPI specification for the public account-level integration surface."
  },
  "paths": {
    "/devices": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns all devices belonging to the authenticated user. Each item also carries the cashier-card figures:\nthe masked Kaspi phone of the latest session, today's paid revenue through the device (Kazakhstan time, payments of the owner's organization, billing top-ups excluded)\nand how many payment links and booking cards use the device.\nsession_problem_since is when Kaspi stopped accepting the device's session (the cashier stays active, payments through it may fail);\nnull while it works, and for the first 10 minutes of a problem.\nFor a cashier (role cashier) the list holds only the active cashboxes assigned to them, in the same shape, with revenue_today 0 and used_in zero.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "devices"
        ],
        "summary": "List devices",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.deviceListResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Starts Kaspi phone registration, requests OTP, and returns challenge_id for confirmation.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "devices"
        ],
        "summary": "Add a device",
        "parameters": [
          {
            "description": "Start add device request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.startAddDeviceRequest"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Accepted",
            "schema": {
              "$ref": "#/definitions/handler.startAddDeviceResponse"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "402": {
            "description": "DEVICE_LIMIT_EXCEEDED, or EXTRA_DEVICE_OVERDRAFT when the extra-device charge would exceed the overdraft limit (not returned when the plan has allow_device_overdraft)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "DEVICE_NAME_TAKEN",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/devices/{deviceID}": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns details of a specific device owned by the authenticated user. session_problem_since is when Kaspi stopped\naccepting the device's session (null while it works, and for the first 10 minutes of a problem).",
        "produces": [
          "application/json"
        ],
        "tags": [
          "devices"
        ],
        "summary": "Get a device",
        "parameters": [
          {
            "type": "string",
            "description": "Device ID",
            "name": "deviceID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.deviceDetailObject"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "put": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Updates the fields present in the body; an omitted or null field is left unchanged.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "devices"
        ],
        "summary": "Update a device",
        "parameters": [
          {
            "type": "string",
            "description": "Device ID",
            "name": "deviceID",
            "in": "path",
            "required": true
          },
          {
            "description": "Update request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.updateDeviceRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.updateDeviceResponse"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "DEVICE_NAME_TAKEN",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Removes a device and all its API keys.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "devices"
        ],
        "summary": "Remove a device",
        "parameters": [
          {
            "type": "string",
            "description": "Device ID",
            "name": "deviceID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/devices/{deviceID}/keys": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns all API keys for a specific device.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "device-keys"
        ],
        "summary": "List device API keys",
        "parameters": [
          {
            "type": "string",
            "description": "Device ID",
            "name": "deviceID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.deviceKeyListResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Creates a new API key for the specified device.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "device-keys"
        ],
        "summary": "Create a device API key",
        "parameters": [
          {
            "type": "string",
            "description": "Device ID",
            "name": "deviceID",
            "in": "path",
            "required": true
          },
          {
            "description": "Create key request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.createDeviceKeyRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.deviceKeyCreatedObject"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "DEVICE_NOT_FOUND — the device does not exist or belongs to another user",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/devices/{deviceID}/keys/{keyID}": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns details of a specific device API key.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "device-keys"
        ],
        "summary": "Get a device API key",
        "parameters": [
          {
            "type": "string",
            "description": "Device ID",
            "name": "deviceID",
            "in": "path",
            "required": true
          },
          {
            "type": "string",
            "description": "Key ID",
            "name": "keyID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.deviceKeyDetailResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Revokes a device API key with an optional reason.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "device-keys"
        ],
        "summary": "Revoke a device API key",
        "parameters": [
          {
            "type": "string",
            "description": "Device ID",
            "name": "deviceID",
            "in": "path",
            "required": true
          },
          {
            "type": "string",
            "description": "Key ID",
            "name": "keyID",
            "in": "path",
            "required": true
          },
          {
            "description": "Revoke request",
            "name": "body",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/handler.revokeKeyRequest"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "Conflict",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/devices/confirm": {
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Confirms OTP challenge and creates the UserDevice. No API key is issued automatically.\nTo create an API key call POST /v1/devices/{deviceID}/keys after this step.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "devices"
        ],
        "summary": "Confirm add device",
        "parameters": [
          {
            "description": "Confirm request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.confirmAddDeviceRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.confirmDeviceResponse"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "CHALLENGE_EXPIRED, CHALLENGE_ALREADY_USED, or DEVICE_NAME_TAKEN when another active device took the name meanwhile",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/me/pats": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "personal-access-tokens"
        ],
        "summary": "List personal access tokens",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/handler.patResponse"
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Creates a long-lived PAT (xusr_pat_*) for server-to-server integrations.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "personal-access-tokens"
        ],
        "summary": "Issue a personal access token",
        "parameters": [
          {
            "description": "Issue PAT request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.issuePATRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.patCreatedResponse"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/me/pats/{patID}": {
      "delete": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "tags": [
          "personal-access-tokens"
        ],
        "summary": "Revoke a personal access token",
        "parameters": [
          {
            "type": "string",
            "description": "PAT ID",
            "name": "patID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/orgs/me": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "organizations"
        ],
        "summary": "Get current organization",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.orgResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "patch": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Owner only. Omitted fields are left unchanged; an empty `support_whatsapp` clears the number. The number is normalized to +7XXXXXXXXXX. An empty `display_name` is rejected.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "organizations"
        ],
        "summary": "Update organization (display name, support WhatsApp)",
        "parameters": [
          {
            "description": "Update request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.updateOrgRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.orgResponse"
            }
          },
          "400": {
            "description": "VALIDATION_ERROR — invalid body or empty display_name; INVALID_PHONE — support_whatsapp is not a Kazakhstan mobile number",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "FORBIDDEN — not the organization owner",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "ORGANIZATION_NOT_FOUND",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/orgs/me/members": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "organizations"
        ],
        "summary": "List organization members",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/handler.memberResponse"
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "Forbidden",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "organizations"
        ],
        "summary": "Onboard a new member (start Kaspi OTP)",
        "parameters": [
          {
            "description": "Onboard request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.createMemberRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.onboardResult"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "Forbidden",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "DEVICE_NAME_TAKEN",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/orgs/me/members/{userID}": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "organizations"
        ],
        "summary": "Get a member",
        "parameters": [
          {
            "type": "string",
            "description": "Member user ID",
            "name": "userID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.memberResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "Forbidden",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "MEMBER_NOT_FOUND — the id is a cashier's (cashiers are managed under /orgs/me/cashiers)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "tags": [
          "organizations"
        ],
        "summary": "Revoke a member",
        "parameters": [
          {
            "type": "string",
            "description": "Member user ID",
            "name": "userID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "Forbidden",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "MEMBER_NOT_FOUND — the id is a cashier's (cashiers are managed under /orgs/me/cashiers)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/orgs/me/members/{userID}/devices": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "organizations"
        ],
        "summary": "List devices for a member",
        "parameters": [
          {
            "type": "string",
            "description": "Member user ID",
            "name": "userID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "Forbidden",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "MEMBER_NOT_FOUND — the id is a cashier's (cashiers are managed under /orgs/me/cashiers)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "organizations"
        ],
        "summary": "Start adding a device for a member (Kaspi OTP step 1)",
        "parameters": [
          {
            "type": "string",
            "description": "Member user ID",
            "name": "userID",
            "in": "path",
            "required": true
          },
          {
            "description": "Device request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.addMemberDeviceRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.onboardResult"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "Forbidden",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "MEMBER_NOT_FOUND — the id is a cashier's (cashiers are managed under /orgs/me/cashiers)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "DEVICE_NAME_TAKEN",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/orgs/me/members/{userID}/devices/{deviceID}/keys": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "organizations"
        ],
        "summary": "List API keys for a member's device",
        "parameters": [
          {
            "type": "string",
            "description": "Member user ID",
            "name": "userID",
            "in": "path",
            "required": true
          },
          {
            "type": "string",
            "description": "Device ID",
            "name": "deviceID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "Forbidden",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "MEMBER_NOT_FOUND — the id is a cashier's (cashiers are managed under /orgs/me/cashiers)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/orgs/me/members/{userID}/devices/confirm": {
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "organizations"
        ],
        "summary": "Confirm device addition for a member (Kaspi OTP step 2)",
        "parameters": [
          {
            "type": "string",
            "description": "Member user ID",
            "name": "userID",
            "in": "path",
            "required": true
          },
          {
            "description": "Confirm request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.confirmMemberDeviceRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.confirmResult"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "403": {
            "description": "Forbidden",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "MEMBER_NOT_FOUND — the id is a cashier's (cashiers are managed under /orgs/me/cashiers)",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "DEVICE_NAME_TAKEN",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns a paginated list of payments for the authenticated device API key owner.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "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 the device's device_name (case-insensitive)",
            "name": "device_name",
            "in": "query"
          },
          {
            "type": "string",
            "description": "Pagination cursor from previous response",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.paymentListResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Initiates a new Kaspi QR payment for the authenticated device API key.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "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.createPaymentRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.paymentObject"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "DEVICE_NOT_FOUND — the device does not exist or belongs to another organization",
            "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": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns payment details by ID.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "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"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments/{paymentID}/cancel": {
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Cancels a pending payment.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "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"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "409": {
            "description": "Conflict",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments/{paymentID}/refund": {
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Initiates a refund for a completed payment.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "refunds"
        ],
        "summary": "Create a refund",
        "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"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "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"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments/{paymentID}/refunds": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns all refunds for a given payment.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "refunds"
        ],
        "summary": "List refunds for a payment",
        "parameters": [
          {
            "type": "string",
            "description": "Payment ID",
            "name": "paymentID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.refundListResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/payments/link": {
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Generates a Kaspi QR payment link for the given amount. The returned qr_token URL can be displayed as a QR code or opened directly by the payer.\nWhen merchant_order_id is supplied, links issued earlier for the same order and still awaiting payment are cancelled, unless Kaspi reports one of them as already paid. Those cancellations emit no webhook, so an order never reports payment.expired after moving on to a newer link.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "payments"
        ],
        "summary": "Create a payment link",
        "parameters": [
          {
            "description": "Payment link request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.createPaymentLinkRequest"
            }
          }
        ],
        "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 — the device does not exist or belongs to another organization",
            "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": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns a paginated list of all refunds for the authenticated merchant.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "refunds"
        ],
        "summary": "List refunds",
        "parameters": [
          {
            "type": "string",
            "description": "Filter by payment ID",
            "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"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/refunds/{refundID}": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns refund details by ID.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "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"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/static-qr-payments/{orderNumber}": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns a static QR (Link) payment record fetched from Kaspi history. Only payments received through a device of the caller's organization are visible; any other order number answers 404.\nNot in the sandbox: a test key (xdev_test_…) gets 404 NOT_AVAILABLE_IN_SANDBOX.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "static-qr"
        ],
        "summary": "Get static QR payment by order number",
        "parameters": [
          {
            "type": "string",
            "description": "Kaspi order number (e.g. QR15029656207)",
            "name": "orderNumber",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.staticQrPaymentObject"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns all webhook subscriptions for the authenticated merchant, with their delivery health: last_success_at, last_failure_at,\nfailure_count (failed attempts since the last success) and failing_since (set while a delivery has failed after every attempt and none has succeeded since).",
        "produces": [
          "application/json"
        ],
        "tags": [
          "webhooks"
        ],
        "summary": "List webhook subscriptions",
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.subscriptionListResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Registers a new webhook endpoint for payment event notifications.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "webhooks"
        ],
        "summary": "Create a webhook subscription",
        "parameters": [
          {
            "description": "Subscription request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.createSubscriptionRequest"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/handler.subscriptionObject"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/webhooks/{subscriptionID}": {
      "put": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Updates the URL, events, or active state of a webhook subscription.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "webhooks"
        ],
        "summary": "Update a webhook subscription",
        "parameters": [
          {
            "type": "string",
            "description": "Subscription ID",
            "name": "subscriptionID",
            "in": "path",
            "required": true
          },
          {
            "description": "Update request",
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/handler.updateSubscriptionRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.subscriptionObject"
            }
          },
          "400": {
            "description": "Bad Request",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Permanently removes a webhook subscription.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "webhooks"
        ],
        "summary": "Delete a webhook subscription",
        "parameters": [
          {
            "type": "string",
            "description": "Subscription ID",
            "name": "subscriptionID",
            "in": "path",
            "required": true
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/webhooks/{subscriptionID}/deliveries": {
      "get": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Returns the delivery history for a webhook subscription.",
        "produces": [
          "application/json"
        ],
        "tags": [
          "webhooks"
        ],
        "summary": "List webhook deliveries",
        "parameters": [
          {
            "type": "string",
            "description": "Subscription ID",
            "name": "subscriptionID",
            "in": "path",
            "required": true
          },
          {
            "type": "string",
            "description": "Filter by status (PENDING, SUCCESS, FAILED, EXHAUSTED)",
            "name": "status",
            "in": "query"
          },
          {
            "type": "string",
            "description": "Pagination cursor",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.deliveryListResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "500": {
            "description": "Internal Server Error",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    },
    "/webhooks/{subscriptionID}/test": {
      "post": {
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "description": "Sends a test event payload to the subscription's URL to verify connectivity.",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "tags": [
          "webhooks"
        ],
        "summary": "Test a webhook subscription",
        "parameters": [
          {
            "type": "string",
            "description": "Subscription ID",
            "name": "subscriptionID",
            "in": "path",
            "required": true
          },
          {
            "description": "Event to test",
            "name": "body",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/handler.testDeliveryRequest"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/handler.testDeliveryResponse"
            }
          },
          "401": {
            "description": "Unauthorized",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          },
          "422": {
            "description": "Unprocessable Entity",
            "schema": {
              "$ref": "#/definitions/handler.errorResponse"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "handler.addMemberDeviceRequest": {
      "type": "object",
      "properties": {
        "api_device_name": {
          "description": "APIDeviceName is the device's v2 API name: optional, 1–32 Latin letters or digits.",
          "type": "string",
          "example": "Kassa2"
        },
        "device_description": {
          "type": "string",
          "example": "Second register"
        },
        "device_name": {
          "description": "display name, e.g. \"Касса 1\"",
          "type": "string",
          "example": "POS Terminal 2"
        },
        "phone": {
          "type": "string",
          "example": "+77001234567"
        }
      }
    },
    "handler.cancelPaymentRequest": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "example": "Customer requested cancellation"
        }
      }
    },
    "handler.cashierObject": {
      "type": "object",
      "properties": {
        "created_at": {
          "type": "string"
        },
        "description": {
          "type": "string",
          "example": "Main POS terminal"
        },
        "device_name": {
          "description": "null when not set",
          "type": "string",
          "example": "Kassa1"
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "name": {
          "type": "string",
          "example": "Store Terminal 1"
        },
        "organization_name": {
          "type": "string",
          "example": "ТОО МегаМаркет"
        },
        "phone_masked": {
          "description": "PhoneMasked is the Kaspi phone of the latest session, e.g. \"+7 702 ••• •• 06\"; null when unknown.",
          "type": "string",
          "example": "+7 702 ••• •• 06"
        },
        "revenue_today": {
          "description": "RevenueToday is the gross paid amount through the device since 00:00 Kazakhstan time (payments of the owner's organization, billing top-ups excluded).",
          "type": "number",
          "example": 5000
        },
        "session_problem_since": {
          "description": "SessionProblemSince is when Kaspi stopped accepting the device's session; null while it works.",
          "type": "string",
          "example": "2026-10-21T09:05:00Z"
        },
        "status": {
          "type": "integer",
          "example": 1
        },
        "updated_at": {
          "type": "string"
        },
        "used_in": {
          "description": "UsedIn counts the active or draft payment links and the active booking cards using the device.",
          "allOf": [
            {
              "$ref": "#/definitions/handler.cashierUsage"
            }
          ]
        }
      }
    },
    "handler.cashierUsage": {
      "type": "object",
      "properties": {
        "booking_resources": {
          "type": "integer",
          "example": 1
        },
        "links": {
          "type": "integer",
          "example": 2
        }
      }
    },
    "handler.confirmAddDeviceRequest": {
      "type": "object",
      "required": [
        "challenge_id",
        "otp"
      ],
      "properties": {
        "challenge_id": {
          "type": "string",
          "example": "uuid"
        },
        "otp": {
          "type": "string",
          "example": "123456"
        }
      }
    },
    "handler.confirmDeviceResponse": {
      "type": "object",
      "properties": {
        "device": {
          "$ref": "#/definitions/handler.deviceObject"
        }
      }
    },
    "handler.confirmMemberDeviceRequest": {
      "type": "object",
      "properties": {
        "challenge_id": {
          "type": "string",
          "example": "uuid"
        },
        "otp": {
          "type": "string",
          "example": "123456"
        }
      }
    },
    "handler.confirmResult": {
      "type": "object",
      "properties": {
        "api_key": {
          "type": "string",
          "example": "xdev_..."
        },
        "device_id": {
          "type": "string",
          "example": "uuid"
        }
      }
    },
    "handler.createDeviceKeyRequest": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "example": "default"
        }
      }
    },
    "handler.createMemberRequest": {
      "type": "object",
      "properties": {
        "api_device_name": {
          "description": "APIDeviceName is the device's v2 API name: optional, 1–32 Latin letters or digits.",
          "type": "string",
          "example": "Kassa1"
        },
        "device_description": {
          "type": "string",
          "example": "Main register"
        },
        "device_name": {
          "description": "display name, e.g. \"Касса 1\"",
          "type": "string",
          "example": "POS Terminal 1"
        },
        "display_name": {
          "type": "string",
          "example": "John Doe"
        },
        "email": {
          "type": "string",
          "example": "member@example.com"
        },
        "phone": {
          "type": "string",
          "example": "+77001234567"
        }
      }
    },
    "handler.createPaymentLinkRequest": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "example": 1500
        },
        "merchant_order_id": {
          "type": "string",
          "example": "order-uuid"
        }
      }
    },
    "handler.createPaymentRequest": {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "example": 1500
        },
        "comment": {
          "type": "string",
          "example": "Order #42"
        },
        "merchant_order_id": {
          "type": "string",
          "example": "order-uuid"
        },
        "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.createSubscriptionRequest": {
      "type": "object",
      "properties": {
        "description": {
          "type": "string",
          "example": "Production webhook"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "payment.completed",
            "payment.cancelled"
          ]
        },
        "secret": {
          "type": "string",
          "example": "my-secret"
        },
        "url": {
          "type": "string",
          "example": "https://example.com/webhook"
        }
      }
    },
    "handler.deliveryListResponse": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.deliveryObject"
          }
        },
        "has_more": {
          "type": "boolean",
          "example": false
        },
        "next_cursor": {
          "type": "string",
          "example": ""
        }
      }
    },
    "handler.deliveryObject": {
      "type": "object",
      "properties": {
        "attempt_number": {
          "type": "integer",
          "example": 1
        },
        "created_at": {
          "type": "string"
        },
        "delivered_at": {
          "type": "string"
        },
        "event": {
          "type": "string",
          "example": "payment.completed"
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "payment_id": {
          "type": "string",
          "example": "uuid"
        },
        "response_code": {
          "type": "integer",
          "example": 200
        },
        "status": {
          "type": "string",
          "example": "delivered"
        },
        "subscription_id": {
          "type": "string",
          "example": "uuid"
        }
      }
    },
    "handler.deviceDetailObject": {
      "type": "object",
      "properties": {
        "created_at": {
          "type": "string"
        },
        "description": {
          "type": "string",
          "example": "Main POS terminal"
        },
        "device_name": {
          "description": "null when not set",
          "type": "string",
          "example": "Kassa1"
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "name": {
          "type": "string",
          "example": "Store Terminal 1"
        },
        "organization_name": {
          "type": "string",
          "example": "ТОО МегаМаркет"
        },
        "session_problem_since": {
          "description": "SessionProblemSince is when Kaspi stopped accepting the device's session; null while it works.",
          "type": "string",
          "example": "2026-10-21T09:05:00Z"
        },
        "static_qr_sync": {
          "type": "boolean",
          "example": false
        },
        "status": {
          "type": "integer",
          "example": 1
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "handler.deviceKeyCreatedObject": {
      "type": "object",
      "properties": {
        "created_at": {
          "type": "string"
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "key_prefix": {
          "type": "string",
          "example": "xdk_"
        },
        "name": {
          "type": "string",
          "example": "default"
        },
        "raw_key": {
          "type": "string",
          "example": "xdk_live_..."
        }
      }
    },
    "handler.deviceKeyDetailResponse": {
      "type": "object",
      "properties": {
        "created_at": {
          "type": "string"
        },
        "device_id": {
          "type": "string",
          "example": "uuid"
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "key_prefix": {
          "type": "string",
          "example": "xdk_"
        },
        "name": {
          "type": "string",
          "example": "default"
        },
        "revoked_at": {
          "type": "string"
        },
        "revoked_reason": {
          "type": "string"
        }
      }
    },
    "handler.deviceKeyListResponse": {
      "type": "object",
      "properties": {
        "keys": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.deviceKeyObject"
          }
        }
      }
    },
    "handler.deviceKeyObject": {
      "type": "object",
      "properties": {
        "created_at": {
          "type": "string"
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "key_prefix": {
          "type": "string",
          "example": "xdk_"
        },
        "name": {
          "type": "string",
          "example": "default"
        },
        "revoked_at": {
          "type": "string"
        },
        "revoked_reason": {
          "type": "string"
        }
      }
    },
    "handler.deviceListResponse": {
      "type": "object",
      "properties": {
        "devices": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/handler.cashierObject"
          }
        }
      }
    },
    "handler.deviceObject": {
      "type": "object",
      "properties": {
        "created_at": {
          "type": "string"
        },
        "description": {
          "type": "string",
          "example": "Main POS terminal"
        },
        "device_name": {
          "description": "null when not set",
          "type": "string",
          "example": "Kassa1"
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "name": {
          "type": "string",
          "example": "Store Terminal 1"
        },
        "organization_name": {
          "type": "string",
          "example": "ТОО МегаМаркет"
        },
        "status": {
          "type": "integer",
          "example": 1
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "handler.errorResponse": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "example": "VALIDATION_ERROR"
        },
        "message": {
          "type": "string",
          "example": "payer_phone and amount are required"
        }
      }
    },
    "handler.issuePATRequest": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "example": "Production integration"
        }
      }
    },
    "handler.memberResponse": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "organization_id": {
          "type": "string",
          "example": "uuid"
        },
        "role": {
          "type": "string",
          "example": "member"
        }
      }
    },
    "handler.onboardResult": {
      "type": "object",
      "properties": {
        "challenge_id": {
          "type": "string",
          "example": "uuid"
        },
        "password": {
          "type": "string",
          "example": "abc123"
        },
        "user_created": {
          "type": "boolean",
          "example": true
        },
        "user_id": {
          "type": "string",
          "example": "uuid"
        }
      }
    },
    "handler.orgResponse": {
      "type": "object",
      "properties": {
        "display_name": {
          "type": "string",
          "example": "My Company"
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "kind": {
          "type": "string",
          "example": "partner"
        },
        "owner_user_id": {
          "type": "string",
          "example": "uuid"
        },
        "support_whatsapp": {
          "description": "SupportWhatsApp is the number xPayment support uses to reach the organization; null when unset.",
          "type": "string",
          "example": "+77021967506"
        }
      }
    },
    "handler.patCreatedResponse": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "name": {
          "type": "string",
          "example": "Production integration"
        },
        "raw_token": {
          "type": "string",
          "example": "xusr_pat_..."
        },
        "token_prefix": {
          "type": "string",
          "example": "xusr_pat_a1b2c3d4e5f"
        }
      }
    },
    "handler.patResponse": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "name": {
          "type": "string",
          "example": "Production integration"
        },
        "token_prefix": {
          "type": "string",
          "example": "xusr_pat_a1b2c3d4e5f"
        }
      }
    },
    "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.revokeKeyRequest": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string",
          "example": "Compromised"
        }
      }
    },
    "handler.startAddDeviceRequest": {
      "type": "object",
      "required": [
        "device_name",
        "name",
        "phone"
      ],
      "properties": {
        "description": {
          "type": "string",
          "example": "Main POS terminal"
        },
        "device_name": {
          "description": "DeviceName is the stable API name the v2 payments API addresses the device by:\n1–32 Latin letters or digits, unique (case-insensitively) among the user's active devices.",
          "type": "string",
          "example": "Kassa1"
        },
        "name": {
          "type": "string",
          "example": "Store Terminal 1"
        },
        "phone": {
          "type": "string",
          "example": "+77001234567"
        }
      }
    },
    "handler.startAddDeviceResponse": {
      "type": "object",
      "properties": {
        "challenge_id": {
          "type": "string",
          "example": "uuid"
        },
        "expires_at": {
          "type": "string"
        }
      }
    },
    "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.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.testDeliveryRequest": {
      "type": "object",
      "properties": {
        "event": {
          "type": "string",
          "example": "payment.completed"
        }
      }
    },
    "handler.testDeliveryResponse": {
      "type": "object",
      "properties": {
        "subscription_id": {
          "type": "string",
          "example": "uuid"
        },
        "success": {
          "type": "boolean",
          "example": true
        }
      }
    },
    "handler.updateDeviceRequest": {
      "type": "object",
      "properties": {
        "description": {
          "description": "Description; omitted or null leaves it unchanged.",
          "type": "string",
          "example": "Updated terminal description"
        },
        "device_name": {
          "description": "DeviceName renames the device's API name; omitted or null leaves it unchanged, \"\" is rejected.",
          "type": "string",
          "example": "Kassa1"
        },
        "name": {
          "description": "Name is the display name; omitted or null leaves it unchanged.",
          "type": "string",
          "example": "Updated Terminal"
        }
      }
    },
    "handler.updateDeviceResponse": {
      "type": "object",
      "properties": {
        "description": {
          "type": "string",
          "example": "Updated terminal description"
        },
        "device_name": {
          "type": "string",
          "example": "Kassa1"
        },
        "id": {
          "type": "string",
          "example": "uuid"
        },
        "name": {
          "type": "string",
          "example": "Updated Terminal"
        },
        "updated_at": {
          "type": "string"
        }
      }
    },
    "handler.updateOrgRequest": {
      "type": "object",
      "properties": {
        "display_name": {
          "description": "DisplayName is optional; when sent it must not be blank.",
          "type": "string",
          "example": "New Company Name"
        },
        "support_whatsapp": {
          "description": "SupportWhatsApp is optional; any common KZ spelling is accepted (\"8 702 196 75 06\"),\n\"\" clears it. Stored and returned as +7XXXXXXXXXX.",
          "type": "string",
          "example": "+77021967506"
        }
      }
    },
    "handler.updateSubscriptionRequest": {
      "type": "object",
      "properties": {
        "description": {
          "type": "string",
          "example": "Updated webhook"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "payment.completed"
          ]
        },
        "is_active": {
          "type": "boolean",
          "example": true
        },
        "url": {
          "type": "string",
          "example": "https://example.com/webhook"
        }
      }
    }
  },
  "host": "api.xpayment.kz",
  "basePath": "/v1",
  "schemes": [
    "https"
  ]
}
