// Типы KazPayment SDK. Поля ответов — как в документации: https://kazpayment.kz/docs/api export interface KazPaymentOptions { /** Ключ интеграции из кабинета: «Подключения» → «Интеграция». */ apiKey: string; /** По умолчанию https://kazpayment.kz/api/v1 */ baseUrl?: string; /** Таймаут одного запроса, мс. По умолчанию 15000. */ timeoutMs?: number; /** Сколько раз повторить при 429 и сетевом сбое (только безопасные вызовы). По умолчанию 2. */ maxRetries?: number; fetch?: typeof fetch; } export class KazPaymentError extends Error { readonly status: number; /** Машинный код: `order_not_found`, `rate_limited`, `free_order_limit`, `network`, `bad_response`… */ readonly code: string; readonly retryAfterSeconds: number | null; readonly body: unknown; } export type OrderStatus = 'pending' | 'paid' | 'cancelled'; export interface Order { orderRef: string; amount: number; paidAmount: number; refundedAmount?: number; status: OrderStatus; /** true — заведён этим вызовом, false — найден по номеру. */ created: boolean; /** Только в ответе создания и только у неоплаченного заказа. */ payUrl?: string; /** Kaspi не принял счёт на `customer_phone` — причина; предложите другой способ оплаты. */ invoiceError?: string; /** Когда уйдёт новый счёт вместо исчезнувшего из Kaspi. */ nextInvoiceAt?: string; /** Что покупатель увидит в счёте Kaspi — есть и в песочнице. */ invoiceText?: string; } export interface CreateOrderInput { /** Номер заказа в ВАШЕЙ системе, до 128 символов. */ externalRef: string; /** Целое число тенге. */ amount: number; comment?: string; customerPhone?: string; returnUrl?: string; /** false — не выставлять счёт в Kaspi самим, ждать выбора на странице оплаты. */ autoInvoice?: boolean; /** Текст счёта в Kaspi ровно как есть, до 200 символов: без «Заказ», номера и смены регистра. */ invoiceText?: string; } export interface RefundResult { refunded: number; remaining: number; /** true — ответ по вашему прежнему запросу, денег второй раз не трогали. */ repeated: boolean; } export interface CancelResult { orderRef: string; status: 'cancelled'; /** true — заказ был отменён раньше, повтор ничего не трогал. */ repeated: boolean; /** Сколько уже было получено по заказу, ₸ (у частично оплаченного). */ paidAmount: number; /** false — касса не ответила; счёт в Kaspi kazpayment погасит сам в ближайшие минуты. */ invoiceClosed: boolean; } export interface Plan { id: string; name: string; amount: number; interval: string; /** «Каждые N дней от оплаты»: 7, 30, 90, 365; null — по календарю (`interval`). */ cycle_days: number | null; /** Неделя — день недели 1..7 (пн..вс); иначе null. */ due_weekday: number | null; /** Месяц — число месяца 1..31; квартал и год — 1 (первый день периода); иначе null. */ due_day: number | null; /** Квартал и год — 1 (первый месяц периода); иначе null. */ due_month: number | null; /** Период «Свой»: ММ-ДД начала и конца, каждый год; иначе null. */ custom_from: string | null; custom_to: string | null; /** Пришёл посреди периода: полная сумма, за оставшиеся месяцы или дни. */ prorate: 'full' | 'months' | 'days'; status: string; /** Только у тарифов-подписок: правило неоплаты тарифа. */ unpaid_policy?: PlanUnpaidPolicy; } export type PlanUnpaidPolicy = { own: false } | { own: true; mode: UnpaidMode; days: number | null; missed_periods_max: number | null }; export interface Payer { id: string; phone: string; full_name: string | null; email?: string | null; status?: string; created: boolean; } export interface Subscription { id: string; payer_id: string; payer_phone: string; plan_id: string; plan_name: string; amount: number; starts_on: string; ends_on: string | null; status: 'active' | 'paused' | 'cancelled'; /** `no_response` (в том числе сама по неоплате), `price`, `left`, `quality`, `other`; null — не отменена. */ cancel_reason: string | null; cancelled_at: string | null; /** Просроченный неоплаченный остаток, ₸, и число таких счетов. */ debt_amount: number; overdue_charges: number; /** Только в ответе создания: пропущенные периоды прежней подписки в первом счёте. */ missed_periods?: number; } export type UnpaidMode = 'debt' | 'merge' | 'forgive' | 'cancel'; export interface UnpaidPolicy { mode: UnpaidMode; days: number | null; missed_periods_max: number | null; /** Дней до нового счёта, если прежний исчез из Kaspi; 0 — сразу. */ reissue_pause_days: number; } export interface WebhookEvent { event_id: string; event: 'payment.received' | 'order.refunded' | 'webhook.test' | string; occurred_at: string; order_ref: string | null; charge_id: string; subscription_id?: string | null; payer_id?: string | null; amount: number; paid_amount: number; refunded_amount?: number; } export class KazPayment { constructor(options: KazPaymentOptions); request(method: string, path: string, body?: unknown, opts?: { idempotent?: boolean; timeoutMs?: number }): Promise; whoami(): Promise<{ tenantId: string | null; role: string }>; kaspiStatus(): Promise<{ connected: boolean; checkedAt: string | null; since: string | null }>; /** Показатели бизнеса: `part` — раздел (без него — оплаты), `month` — `ГГГГ-ММ`. */ getMetrics>(opts?: { part?: string; month?: string }): Promise; setMetricsDigest(enabled: boolean): Promise<{ enabled: boolean }>; createOrder(input: CreateOrderInput): Promise; getOrder(externalRef: string): Promise; refundOrder(externalRef: string, input: { amount: number; reason: string; refundRef: string }): Promise; cancelOrder(externalRef: string, input?: { reason?: string }): Promise; /** Ошибки: `invoice_rejected` — на номере нет Kaspi; `invoice_already_paid` — прежний счёт оплачен, снова платить не надо. */ sendInvoice(externalRef: string, input: { phone: string }): Promise<{ orderRef: string; sent: boolean }>; notifyOrder(externalRef: string, input?: { channel?: 'whatsapp'; link?: string; amount?: string; lang?: 'ru' | 'kk' }): Promise>; listPlans(): Promise<{ plans: Plan[] }>; createPayer(input: { phone: string; fullName?: string; email?: string; lang?: 'ru' | 'kk' }): Promise; createSubscription(input: { payerPhone: string; planId: string; startsOn?: string; endsOn?: string; amount?: number }): Promise; listSubscriptions(input?: { payerPhone?: string }): Promise<{ subscriptions: Subscription[] }>; setSubscriptionStatus(id: string, status: 'active' | 'paused' | 'cancelled'): Promise; getUnpaidPolicy(): Promise; setUnpaidPolicy(input: { mode?: UnpaidMode; days?: number | null; missedPeriodsMax?: number | null; reissuePauseDays?: number }): Promise; getPlanUnpaidPolicy(planId: string): Promise; setPlanUnpaidPolicy(planId: string, input: { own: false } | { own: true; mode: UnpaidMode; days?: number | null; missedPeriodsMax?: number | null }): Promise; getAutoBilling(): Promise<{ paused: boolean; subscriptions: number; kassa_connected: boolean }>; startAutoBilling(): Promise<{ paused: boolean; subscriptions: number; kassa_connected: boolean }>; sendSms(input: { phone: string; text: string; kind?: 'service' | 'marketing' }): Promise>; whatsappOrder(input: { phone: string; order: string; state: string; lang?: 'ru' | 'kk' }): Promise>; whatsappCart(input: { phone: string; items: string; total: string; lang?: 'ru' | 'kk' }): Promise>; requestOtp(input: { phone: string; idempotencyKey?: string }): Promise<{ requestId: string; priceKzt?: number }>; verifyOtp(input: { requestId: string; code: string }): Promise<{ validated: boolean; phone: string | null }>; setWebhook(url: string): Promise<{ url: string; secret: string }>; getWebhook(): Promise>; deleteWebhook(): Promise<{ removed: boolean }>; testWebhook(): Promise<{ queued: boolean }>; } export function verifyWebhookSignature(rawBody: string | Buffer, signature: string | undefined | null, secret: string): boolean; export function parseWebhook(rawBody: string | Buffer, signature: string | undefined | null, secret: string): WebhookEvent;