Документация / Библиотеки (SDK)

Библиотеки (SDK)

Официальные библиотеки умеют всё из этой документации и берут на себя скучное: повторы без дублей, разбор ошибок, проверку подписи.

Возможность	Python	Node.js	PHP
Установка	`pip install kivix-pay`	`npm install kivix-pay`	`composer require kivix/pay`
Версия языка	3.9+	18+	8.1+
Счета: создать · найти по заказу · листать · отменить	✅	✅	✅
Проверка подписи вебхука	✅	✅	✅
Автоповтор без дублей	✅	✅	✅
Асинхронный клиент	✅ AsyncKivixPay	✅ Promise	—
Типы	type hints	TypeScript	phpdoc
Зависимости	httpx	нет	ext-curl

Python

pip install kivix-pay

from kivix_pay import KivixPay

pay = KivixPay("kp_...", base_url="https://kivix.cc")
invoice = pay.invoices.create(amount="12.50", asset="USDT", order_id="1001")
print(invoice.pay_url, invoice["status"])   # и через точку, и как dict

Асинхронно (aiogram, FastAPI)

from kivix_pay import AsyncKivixPay

async with AsyncKivixPay("kp_...", base_url="https://kivix.cc") as pay:
    invoice = await pay.invoices.create(amount="5", asset="USDT", order_id="42")

Node.js / TypeScript

npm install kivix-pay

import { KivixPay } from "kivix-pay";   // или require("kivix-pay")

const pay = new KivixPay("kp_...", { baseUrl: "https://kivix.cc" });
const invoice = await pay.invoices.create({ amount: "12.50", asset: "USDT", orderId: "1001" });

PHP

composer require kivix/pay

use Kivix\Pay\KivixPay;

$pay = new KivixPay('kp_...', 'https://kivix.cc');
$invoice = $pay->invoices->create(['amount' => '12.50', 'asset' => 'USDT', 'order_id' => '1001']);

Методы

Что	Python	Node.js	PHP
Создать счёт	`invoices.create(...)`	`invoices.create({...})`	`invoices->create([...])`
Получить	`invoices.get(id)`	`invoices.get(id)`	`invoices->get($id)`
По номеру заказа	`invoices.find_by_order()`	`invoices.findByOrder()`	`invoices->findByOrder()`
Все подряд	`invoices.iterate()`	`for await … iterate()`	`foreach … iterate()`
Отменить	`invoices.cancel(id)`	`invoices.cancel(id)`	`invoices->cancel($id)`
Вебхук	`webhook.set/get/delete/test`	`webhook.set/get/delete/test`	`webhook->set/get/delete/test`
Проверить подпись	`construct_event()`	`constructEvent()`	`Webhook::constructEvent()`
Приложение, баланс, монеты	`me() balance() currencies()`	`me() balance() currencies()`	`me() balance() currencies()`

Ошибки в SDK

Все исключения наследуются от одного базового и содержат HTTP-статус, code и field из ответа API:

Когда	Python	Node.js	PHP
400 — неверный параметр	`InvalidRequestError`	`InvalidRequestError`	`InvalidRequestException`
401 — ключ	`AuthenticationError`	`AuthenticationError`	`AuthenticationException`
404 — не найдено	`NotFoundError`	`NotFoundError`	`NotFoundException`
409 — конфликт	`ConflictError`	`ConflictError`	`ConflictException`
429 — лимит	`RateLimitError`	`RateLimitError`	`RateLimitException`
Сеть	`APIConnectionError`	`APIConnectionError`	`ApiConnectionException`

Надёжность

При обрыве сети, ответах 5xx и 429 SDK сами повторяют запрос — по умолчанию 2 раза, с паузой и с учётом Retry-After. При создании счёта каждый раз отправляется один и тот же Idempotency-Key, поэтому повтор не создаст второй счёт.