API reference

Current integration readiness

Responses

API and D1 table status

not_configured can have status=ok: public pages and search can run without DB. A configured DB with unavailable tables returns 503/degraded. This response does not test Telegram or model network connectivity.

Responses

Public machine-readable contract

Read only. Contains no secrets, sessions, user records or operational payment-provider contract.

Responses

Run due delivery and application jobs

Server scheduler entrypoint. Requires JOBS_SECRET, not a browser session or merchant key. Does not accept job IDs or arbitrary outbound URLs.

Responses

Current session and CSRF

Responses

Start sign-in or registration

Creates a 300-second challenge and an HttpOnly browser-proof cookie; at most six starts per minute per hashed address. Compare the six-digit code on the website and in the private bot chat.

Headers and parameters

JSON body

Responses

Complete a verified sign-in

Requires the proof cookie from start and the same browser. Pending returns 202. After bot confirmation, the request issues one 24-hour session. Up to 90 checks per minute per challenge. A client-supplied Telegram ID is not accepted.

Headers and parameters

JSON body

Responses

End the current session

No body is required or read. The bot's /logout command separately ends all account sessions.

Headers and parameters

Responses

Current user settings

Responses

Change the store name, VAT payer or notifications

All fields are optional: partial patch. Saving vatPayer does not create a financial operation. The payments and payouts switches control preferences, not gateway availability.

Headers and parameters

JSON body

Responses

List owned payment links

Sorted by createdAt DESC, id DESC. Public links work across devices; listing requires an account.

Headers and parameters

Responses

Create an invoice with immutable terms

Create an immutable invoice and immediately receive checkoutUrl; this does not charge the buyer. USD: card/Alipay; RUB: SBP; USDT: crypto. USD crypto remains accepted for compatibility but cannot be paid without a USDT invoice. Fee and VAT customer shares are independent integers from 0 to 100; current live card/Alipay supports VAT customer=100 and fee customer=0. The customer total is never silently changed. Latest website application must be approved before a new live charge. Invoice creation and its merchant event commit atomically.

Headers and parameters

JSON body

Responses

Owned link and saved calculation

Headers and parameters

Responses

Pause, resume or cancel a link

Changes only status. The update and immutable invoice.updated event commit atomically. Concurrent changes use a version check; refresh and retry on LINK_CHANGED. cancelled is terminal, expiration is never extended, and price, methods, cost shares and description stay frozen. Repeating the saved status returns the current invoice.

Headers and parameters

JSON body

Responses

Public invoice details for the customer

Read the immutable public invoice quote and its persisted payment snapshot. method must belong to the invoice. No account is required. Does not expose owner identity, private metadata or merchant proceeds. The token grants access only to this checkout. availability reflects configuration, allocation, technical limits and merchant approval; payment confirmation is separate.

Headers and parameters

Responses

Start or recover the invoice payment

Same-origin buyer operation; no account or CSRF token required. The server reserves one operation and a stable idempotency key before gateway dispatch. A repeat recovers the same operation; a lost response must be resolved through status. The payment method locks after dispatch. Card data must be browser-encrypted with a fresh payment intent. SBP/crypto send the saved customer total; card/Alipay use the supported immutable tax configuration. New charges require an approved merchant application. Existing dispatched payments can be recovered after invoice expiration, pause or approval changes. No /v2 or hosted-card route is used.

Headers and parameters

JSON body

Responses

Read and refresh the same payment

No account is required. Refreshes an existing operation over authenticated gateway transport, with server-side throttling. No new payment is created. Returns null if nothing was dispatched. Confirm an order only when fulfillmentReady is true.

Headers and parameters

Responses

Request an authoritative status reconciliation

Reads the existing operation and asks the gateway to reconcile its provider status. Does not create a payment. At most 3 requests per invoice per minute. Available for already-dispatched payments even if the invoice is no longer active.

Headers and parameters

JSON body

Responses

Obtain a gateway public key and a bound encryption intent

The gateway alone owns the private key. An intent expires within five minutes and binds the merchant order, currency, base/total amounts, operation idempotency key and purpose. payment intents require an active invoice and approved merchant; code intents require an existing, current bank challenge. No PAN, CVV, bank code, or private JWK fields are accepted by this endpoint. At most 8 intents per invoice and 12 per client per minute. The encrypted plaintext is {intent,name,country,email?,card:{number,expiration,cvv,holder}} for payment or {intent,code} for code. Plaintext is assembled only inside the browser before JWE encryption.

Headers and parameters

JSON body

Responses

Relay an encrypted code for the current bank challenge

Obtain a purpose=code intent and encrypt {intent,code} in the browser. The gateway validates the current challenge and consumes the sealed intent once. Kevmi never receives plaintext code. At most 5 submissions per invoice per minute; refresh status after an uncertain response.

Headers and parameters

JSON body

Responses

Read the current coin and network catalog

Only for a USDT invoice that allows crypto. The invoice remains denominated in USDT; the gateway quotes the chosen payer coin. Never assume USD equals USDT or convert the transfer amount to a floating-point number. At most 10 catalog reads per invoice per minute.

Headers and parameters

Responses

Answer from the complete public knowledge base

Public question without a session or CSRF. A supplied Origin must match APP_ORIGIN; agents can omit it. In AI mode, the server sends all published articles, facts, page catalog and feature readiness. Optional history and pageContext are untrusted question context. The model cannot access accounts, money, private requests or tools. With D1, the limit is 12 questions per minute per hashed address. AI requires D1, valid provider configuration and quota: 60 generations per hour service-wide by default. Configuration readiness does not prove external API availability. Provider errors, quota exhaustion or invalid output return search with aiUnavailable=true and HTTP 200. Without generation configuration, regular search is returned.

Headers and parameters

JSON body

Responses

The latest 30 owned support requests

Responses

Save a support request

Up to six requests per user per hour, shared by the website and bot. Saving creates an account record. Keep its reference to ask about status.

Headers and parameters

JSON body

Responses

Read an owned support request

Headers and parameters

Responses

Close an owned support request

The only allowed change is status=closed. This API does not reopen requests, edit messages or submit operator replies.

Headers and parameters

JSON body

Responses

A page of owned notifications

Up to 30 records, sorted by createdAt DESC then id DESC. Listing does not change readAt or trigger delivery. unreadCount is the current user's total unread count across pages. Owner fields, Telegram ID and secrets are excluded.

Headers and parameters

Responses

Mark owned notifications as read

Accepts either ids, or all:true together with before. before is the time of the last observed event and cannot exceed server time. Newer events remain unread. The request is idempotent: existing readAt values do not change. Other users' and missing IDs are neither modified nor disclosed. Telegram status and sentAt remain unchanged.

Headers and parameters

JSON body

Responses

Send a test notification to the account's Telegram

Queues a message and attempts delivery. At most three per user per hour. The test is not a payment notification and does not change a balance. HTTP 202 does not confirm delivery; check the notification list.

Headers and parameters

JSON body

Responses

Receive a Telegram Bot API event

Requires only the Telegram secret header, without session, CSRF or Origin. Additional Update fields are allowed. Handles message and callback_query; personal actions require the verified sender's private chat. Other updates are skipped. update_id is deduplicated; an in-progress update returns 503 for retry. This is not a payment-provider webhook.

JSON body

Responses

Financial operation unavailable

Returns 503 GATEWAY_NOT_CONNECTED. Financial operations are unavailable. The body is not processed and no gateway request is made.

Responses

Financial operation unavailable

Returns 503 GATEWAY_NOT_CONNECTED. Financial operations are unavailable. The body is not processed and no gateway request is made.

Responses

List owned payment links

Sorted by createdAt DESC, id DESC. Public links work across devices; listing requires an account.

Headers and parameters

Responses

Create an invoice with immutable terms

Create an immutable invoice and immediately receive checkoutUrl; this does not charge the buyer. USD: card/Alipay; RUB: SBP; USDT: crypto. USD crypto remains accepted for compatibility but cannot be paid without a USDT invoice. Fee and VAT customer shares are independent integers from 0 to 100; current live card/Alipay supports VAT customer=100 and fee customer=0. The customer total is never silently changed. Latest website application must be approved before a new live charge. Invoice creation and its merchant event commit atomically.

Headers and parameters

JSON body

Responses

Owned link and saved calculation

Headers and parameters

Responses

Pause, resume or cancel a link

Changes only status. The update and immutable invoice.updated event commit atomically. Concurrent changes use a version check; refresh and retry on LINK_CHANGED. cancelled is terminal, expiration is never extended, and price, methods, cost shares and description stay frozen. Repeating the saved status returns the current invoice.

Headers and parameters

JSON body

Responses

List owned payment links

Sorted by createdAt DESC, id DESC. Public links work across devices; listing requires an account.

Headers and parameters

Responses

Create an invoice with immutable terms

Create an immutable invoice and immediately receive checkoutUrl; this does not charge the buyer. USD: card/Alipay; RUB: SBP; USDT: crypto. USD crypto remains accepted for compatibility but cannot be paid without a USDT invoice. Fee and VAT customer shares are independent integers from 0 to 100; current live card/Alipay supports VAT customer=100 and fee customer=0. The customer total is never silently changed. Latest website application must be approved before a new live charge. Invoice creation and its merchant event commit atomically.

Headers and parameters

JSON body

Responses

Owned link and saved calculation

Headers and parameters

Responses

Pause, resume or cancel a link

Changes only status. The update and immutable invoice.updated event commit atomically. Concurrent changes use a version check; refresh and retry on LINK_CHANGED. cancelled is terminal, expiration is never extended, and price, methods, cost shares and description stay frozen. Repeating the saved status returns the current invoice.

Headers and parameters

JSON body

Responses

List own key metadata

Responses

Create a scoped key; reveal its secret once

Maximum 10 active keys. At most 5 creations/hour/user. Keys expire, can be revoked and are rate-limited to 90 API requests/minute/key.

Headers and parameters

JSON body

Responses

Revoke own key

Headers and parameters

Responses

Read own immutable event history

Headers and parameters

Responses

Read own immutable event history

Headers and parameters

Responses

List endpoints and last 30 deliveries

Responses

Register a public HTTPS destination

Up to 5 endpoints and 6 creations/hour/user. Public HTTPS domains only; no credentials, IP literals or custom ports. A newly created endpoint receives no live deliveries until its challenge succeeds.

Headers and parameters

JSON body

Responses

List endpoints and last 30 deliveries

Headers and parameters

Responses

Pause or resume a verified endpoint

Paused verified endpoints keep eligible events in the queue; resuming processes due deliveries.

Headers and parameters

JSON body

Responses

Remove endpoint and cancel undelivered jobs

Cancels pending, failed and leased jobs. A request already sent across the network cannot be recalled.

Headers and parameters

Responses

Send a signed endpoint.verification challenge

Maximum 5 verification attempts/hour/user. Your server must validate Kevmi-Signature and return 2xx JSON {"challenge":"<data.challenge>"}. Request timeout: 8 seconds; response cap: 8192 bytes. Redirects are not followed. Verification activates the endpoint.

Headers and parameters

JSON body

Responses

Replace signing secret and require verification again

Maximum 3 rotations/hour/user. Update your server and verify the endpoint again. An already in-flight request may still carry the previous signature.

Headers and parameters

JSON body

Responses

Retry a failed delivery to an active endpoint

Retains event ID and payload; generates a fresh timestamp and signature. Each automatic delivery cycle makes at most 6 attempts, including expired leases, with delays of 1m, 5m, 30m, 2h and 12h. Delivery is at least once; deduplicate event IDs on your server.

Headers and parameters

JSON body

Responses

List up to 30 own applications

Headers and parameters

Responses

Submit website information and receive a tracking URL

Requires confirmed Telegram sign-in. Up to 5 new submissions/day/user. Idempotent replay returns 200. The server advances real persisted stages; unavailable or risky automatic results require human review. Approval does not configure the payment gateway. Ownership and state cannot be supplied by the applicant.

Headers and parameters

JSON body

Responses

Read own review stages and event history

Headers and parameters

Responses

Resume an eligible background stage

Cannot skip review or approve a stage. A server lease prevents duplicate work. Needs-review and final applications remain unchanged. At most 30 processing-resume requests/minute/user.

Headers and parameters

JSON body

Responses

List up to 100 applications for moderation

Requires the authenticated Telegram identity to be in MODERATOR_TELEGRAM_IDS. Includes all states, ordered needs_review first, processing second, then final states; newest updates first within a group.

Responses

Read review evidence and stage history

Headers and parameters

Responses

Approve the current review stage or decline with a public reason

Requires a configured moderator; at most 30 decisions/minute/user. expectedVersion is compared atomically. Only the current needs_review stage can be approved; final applications cannot be silently reopened. A rejection requires an editable public reason. The decision, stage history and enabled applicant notification are saved together.

Headers and parameters

JSON body

Responses

Receive signed source-native gateway events

Native v3: supply X-Gateway-Timestamp (Unix seconds), X-Gateway-Signature and matching X-Gateway-Event-Id. Maximum timestamp skew is 300 seconds. After signature verification, Kevmi fetches the payment through the authenticated gateway API, checks saved order, exact currency/amount, method and provider-confirmed state, then atomically stores the receipt and merchant outbox event. Webhook text and browser observations alone never confirm a payment. Repeated IDs are deduplicated; a changed body for an existing ID is rejected. Delayed events use fresh authoritative state. Partial refunds, full refunds, disputes and review states are supported. Unbound orders are acknowledged and ignored. Legacy normalized events using Kevmi-Signature remain supported separately; only their succeeded/failed/full-refunded transitions apply.

Headers and parameters

JSON body

Responses