Qut Pay (Kaspi QR payments)

Returns the organization behind the API key: mode (sandbox or live), tariff and limits, connected Kaspi cashiers, provider status. Call this first.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Creates an invoice (QR by default, or pushed to the customer's Kaspi.kz app with kind="phone"). Returns payUrl (hosted pay page), qrImageUrl, deepLink, expiresAt (~3 min). Always pass idempotencyKey (e.g. "order-1001") so a retry never creates a second invoice. Amount in KZT, ≤ 2 decimals; whole tenge for kind="phone".

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Amount in KZT, e.g. 2500 or 1500.5"
    },
    "description": {
      "type": "string",
      "maxLength": 255,
      "description": "Shown to the customer, e.g. \"Order #1001\""
    },
    "externalOrderId": {
      "type": "string",
      "maxLength": 120,
      "description": "Your order id; later GET /invoices?externalOrderId finds it"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Unique per order; same key → same invoice"
    },
    "kind": {
      "type": "string",
      "enum": [
        "qr",
        "phone"
      ],
      "description": "\"qr\" (default) or \"phone\" (invoice pushed into the customer's Kaspi.kz app; needs customer.phone)"
    },
    "customer": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "phone": {
          "type": "string",
          "pattern": "^7\\d{10}$",
          "description": "7XXXXXXXXXX"
        },
        "email": {
          "type": "string",
          "format": "email"
        }
      },
      "additionalProperties": false
    },
    "successUrl": {
      "type": "string",
      "format": "uri"
    },
    "failUrl": {
      "type": "string",
      "format": "uri"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Returned unchanged in webhooks"
    }
  },
  "required": [
    "amount"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Reads one invoice by id (inv_…). live=true asks Kaspi right now instead of the cached status. Status flow: new → pending → paid | failed | expired | cancelled; paid → partially_refunded → refunded.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "live": {
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Lists invoices of the organization, newest first. Filter by status, externalOrderId, date range (ISO), limit ≤ 50, offset for paging.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "new",
        "pending",
        "paid",
        "failed",
        "expired",
        "cancelled",
        "partially_refunded",
        "refunded"
      ]
    },
    "externalOrderId": {
      "type": "string"
    },
    "from": {
      "type": "string",
      "description": "ISO date/time, inclusive"
    },
    "to": {
      "type": "string",
      "description": "ISO date/time, exclusive"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "offset": {
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Closes a pending invoice. A QR may still be paid until expiresAt — then invoice.paid arrives anyway; handle it.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full refund (omit amount) or partial refund of a paid invoice. Needs the refunds:write scope. With a LIVE key real money is returned to the customer, so confirm=true is required and the merchant must have asked for this refund explicitly.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Omit for a full refund"
    },
    "reason": {
      "type": "string",
      "maxLength": 255
    },
    "confirm": {
      "type": "boolean",
      "description": "Required (true) with a live key"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Completes a sandbox invoice as paid / failed / expired without Kaspi, so the whole flow including the merchant's webhook can be tested. Refuses to run with a live key.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "paid",
        "failed",
        "expired"
      ],
      "description": "Default \"paid\""
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read-only list of recurring invoice schedules. Needs the subscriptions:manage scope on the key.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "cancelled"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Reads a recurring invoice schedule by id (sub_…). Needs the subscriptions:manage scope.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}