{ "components": { "schemas": { "CreateMerchantPaymentRequest": { "additionalProperties": false, "description": "Provider-neutral create input. Amount is text so no binary float reaches the money domain.", "properties": { "amount": { "maxLength": 20, "minLength": 4, "pattern": "^(0|[1-9][0-9]{0,16})\\.[0-9]{2}$", "title": "Amount", "type": "string" }, "currency": { "$ref": "#/components/schemas/PaymentCurrency", "default": "KZT" }, "customer_reference": { "anyOf": [ { "maxLength": 30, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Customer Reference" }, "merchant_order_id": { "maxLength": 100, "minLength": 1, "pattern": "^[A-Za-z0-9_.:-]{1,100}$", "title": "Merchant Order Id", "type": "string" } }, "required": [ "amount", "merchant_order_id" ], "title": "CreateMerchantPaymentRequest", "type": "object" }, "CreateWebsiteCashierInvoiceRequest": { "additionalProperties": false, "description": "Create input. ``extra=forbid``: there is no field for a tenant, environment or connection.", "properties": { "amount": { "maxLength": 20, "minLength": 4, "pattern": "^(0|[1-9][0-9]{0,16})\\.[0-9]{2}$", "title": "Amount", "type": "string" }, "currency": { "const": "KZT", "default": "KZT", "title": "Currency", "type": "string" }, "customer_phone": { "maxLength": 15, "minLength": 10, "pattern": "^[0-9]{10,15}$", "title": "Customer Phone", "type": "string" }, "merchant_order_id": { "maxLength": 100, "minLength": 1, "pattern": "^[A-Za-z0-9_.:-]{1,100}$", "title": "Merchant Order Id", "type": "string" } }, "required": [ "amount", "merchant_order_id", "customer_phone" ], "title": "CreateWebsiteCashierInvoiceRequest", "type": "object" }, "ErrorEnvelope": { "properties": { "error": { "properties": { "code": { "description": "Stable machine-readable error code.", "type": "string" }, "message": { "description": "Short non-localized description.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "title": "ErrorEnvelope", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "MerchantPaymentResponse": { "description": "Stable public payment view shared by create, replay, and read. No internal id or org id.\n\n``action`` is additive: it is ``null`` until a provider prepares the customer action, and then a\ndiscriminated ``qr``/``redirect`` object. Clients MUST switch on ``action.type`` and ignore\nunknown future types. It is absent once the payment reaches a terminal state.", "properties": { "action": { "anyOf": [ { "$ref": "#/components/schemas/QrActionResponse" }, { "$ref": "#/components/schemas/RedirectActionResponse" }, { "type": "null" } ], "title": "Action" }, "amount": { "title": "Amount", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "currency": { "$ref": "#/components/schemas/PaymentCurrency" }, "environment": { "title": "Environment", "type": "string" }, "external_account_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Account Number" }, "merchant_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merchant Order Id" }, "reference": { "title": "Reference", "type": "string" }, "status": { "$ref": "#/components/schemas/PaymentStatus" } }, "required": [ "reference", "merchant_order_id", "external_account_number", "status", "amount", "currency", "environment", "created_at" ], "title": "MerchantPaymentResponse", "type": "object" }, "PaymentCurrency": { "description": "Currencies accepted by the provider-neutral payment core.", "enum": [ "KZT" ], "title": "PaymentCurrency", "type": "string" }, "PaymentStatus": { "description": "Minimal provider-neutral payment lifecycle.", "enum": [ "pending", "processing", "succeeded", "cancelled", "failed", "outcome_unknown" ], "title": "PaymentStatus", "type": "string" }, "QrActionResponse": { "description": "A scannable QR customer action. ``value`` is an opaque, provider-neutral payload.", "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "type": { "const": "qr", "default": "qr", "title": "Type", "type": "string" }, "value": { "title": "Value", "type": "string" } }, "required": [ "value" ], "title": "QrActionResponse", "type": "object" }, "RedirectActionResponse": { "description": "A browser-redirect customer action. ``url`` is the customer's HTTPS destination.", "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "type": { "const": "redirect", "default": "redirect", "title": "Type", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "RedirectActionResponse", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" }, "WebsiteCashierInvoiceResponse": { "description": "Stable public view of one website-initiated cashier invoice.\n\n``invoice_state`` says where the Kaspi invoice is; ``payer_action`` is set ONLY while the\ninvoice reached Kaspi and the payment is still open, and then names what the payer must do.\nClients MUST NOT tell the payer to open Kaspi until ``payer_action`` is present, and MUST treat\n``unknown`` as \"do not create another invoice for this order\".", "properties": { "amount": { "title": "Amount", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "currency": { "$ref": "#/components/schemas/PaymentCurrency" }, "environment": { "title": "Environment", "type": "string" }, "invoice_state": { "enum": [ "queued", "sending", "sent", "not_sent", "unknown" ], "title": "Invoice State", "type": "string" }, "merchant_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merchant Order Id" }, "payer_action": { "anyOf": [ { "const": "approve_in_kaspi_app", "type": "string" }, { "type": "null" } ], "title": "Payer Action" }, "reference": { "title": "Reference", "type": "string" }, "settled": { "title": "Settled", "type": "boolean" }, "status": { "$ref": "#/components/schemas/PaymentStatus" } }, "required": [ "reference", "merchant_order_id", "status", "amount", "currency", "environment", "created_at", "invoice_state", "payer_action", "settled" ], "title": "WebsiteCashierInvoiceResponse", "type": "object" } }, "securitySchemes": { "bearerAuth": { "description": "Merchant API key: ep___. Server-side only.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Public Eleven Pay Merchant API (pilot): payments and cashier invoices. The API host is not fixed by this document: set the server variable to the base URL you were given at onboarding. Server-to-server only; the key is a secret.", "title": "Eleven Pay Public API", "version": "0.1.0" }, "openapi": "3.1.0", "paths": { "/v1/cashier/invoices": { "post": { "description": "Stage one Kaspi Cashier invoice for the key's organization. No provider call happens here.", "operationId": "create_website_cashier_invoice_v1_cashier_invoices_post", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebsiteCashierInvoiceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteCashierInvoiceResponse" } } }, "description": "Replay of an earlier identical request (same Idempotency-Key).", "headers": { "Idempotency-Replayed": { "description": "``true`` when this response replays an earlier identical request.", "schema": { "enum": [ "true", "false" ], "type": "string" } } } }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteCashierInvoiceResponse" } } }, "description": "Successful Response", "headers": { "Idempotency-Replayed": { "description": "``true`` when this response replays an earlier identical request.", "schema": { "enum": [ "true", "false" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Idempotency-Key missing or malformed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid, unknown or revoked API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The key lacks the required capability, or the organization is unavailable" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict: idempotency conflict, or the operation is not available in the current state" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited; honour Retry-After" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create Website Cashier Invoice", "tags": [ "merchant-cashier" ] } }, "/v1/cashier/invoices/{reference}": { "get": { "description": "Read one invoice of the key's own organization; unknown and foreign references are alike.", "operationId": "get_website_cashier_invoice_v1_cashier_invoices__reference__get", "parameters": [ { "in": "path", "name": "reference", "required": true, "schema": { "title": "Reference", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteCashierInvoiceResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid, unknown or revoked API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The key lacks the required capability, or the organization is unavailable" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not found (unknown, malformed and foreign references are indistinguishable)" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited; honour Retry-After" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get Website Cashier Invoice", "tags": [ "merchant-cashier" ] } }, "/v1/payments": { "post": { "description": "Create (or safely replay) one pending payment. No provider is contacted.", "operationId": "create_public_payment_v1_payments_post", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantPaymentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPaymentResponse" } } }, "description": "Replay of an earlier identical request (same Idempotency-Key).", "headers": { "Idempotency-Replayed": { "description": "``true`` when this response replays an earlier identical request.", "schema": { "enum": [ "true", "false" ], "type": "string" } } } }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPaymentResponse" } } }, "description": "Successful Response", "headers": { "Idempotency-Replayed": { "description": "``true`` when this response replays an earlier identical request.", "schema": { "enum": [ "true", "false" ], "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Idempotency-Key missing or malformed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid, unknown or revoked API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The key lacks the required capability, or the organization is unavailable" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict: idempotency conflict, or the operation is not available in the current state" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited; honour Retry-After" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create Public Payment", "tags": [ "merchant-payments" ] } }, "/v1/payments/{public_reference}": { "get": { "description": "Return one tenant-owned payment; unknown, malformed, and foreign references are identical.", "operationId": "get_public_payment_v1_payments__public_reference__get", "parameters": [ { "in": "path", "name": "public_reference", "required": true, "schema": { "title": "Public Reference", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantPaymentResponse" } } }, "description": "Successful Response" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Invalid, unknown or revoked API key" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "The key lacks the required capability, or the organization is unavailable" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not found (unknown, malformed and foreign references are indistinguishable)" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limited; honour Retry-After" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service temporarily unavailable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get Public Payment", "tags": [ "merchant-payments" ] } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "description": "Base URL provided at onboarding", "url": "{api_base_url}", "variables": { "api_base_url": { "default": "https://YOUR-ELEVEN-PAY-API-BASE-URL", "description": "No default host is published." } } } ] }