Счета

Счёт — это запрос на оплату: сумма, монета и описание. Покупатель оплачивает его по ссылке pay_url.

Объект счёта

{
  "id": "7Hq2pXbV9kLmN3sT1a",
  "object": "invoice",
  "status": "active",
  "amount": "12.5",
  "asset": "USDT",
  "description": "Заказ #1001",
  "order_id": "1001",
  "payload": null,
  "pay_url": "https://t.me/kivixapp?start=invoice_7Hq2pXbV9kLmN3sT1a",
  "success_url": "https://shop.example/thanks",
  "created_at": "2026-10-26T12:30:00Z",
  "expires_at": "2026-10-26T13:30:00Z",
  "paid_at": null
}

Создать счёт

Ответ: 201 Created и объект счёта. Повтор с тем же order_id — 200 OK и тот же счёт.

Счёт в валюте

Передайте fiat — и укажите цену так, как она стоит у вас в магазине: {"amount": "500", "fiat": "RUB", "asset": "USDT"}. Kivix пересчитает её в монету по курсу в момент создания счёта и округлит вверх до точности монеты — вы получите не меньше запрошенного. Сумма в монете дальше не меняется, сколько бы ни прошло времени. В ответе — amount в монете и fiat / fiat_amount как вы просили. Повтор с тем же order_id сверяется по валютной сумме: курс за это время мог измениться, а счёт останется тем же. Если курс временно недоступен — 503 rate_unavailable, повторите через минуту.

invoice = pay.invoices.create(amount="12.50", asset="USDT", order_id="1001",
                              description="Заказ #1001", expires_in=1800)

const invoice = await pay.invoices.create({ amount: "12.50", asset: "USDT",
  orderId: "1001", description: "Заказ #1001", expiresIn: 1800 });

$invoice = $pay->invoices->create(['amount' => '12.50', 'asset' => 'USDT',
    'order_id' => '1001', 'description' => 'Заказ #1001', 'expires_in' => 1800]);

curl https://kivix.cc/v1/invoices -H "Authorization: Bearer $KIVIX_PAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"12.50","asset":"USDT","order_id":"1001","description":"Заказ #1001","expires_in":1800}'

Как покупатель оплачивает счёт

Покупатель открывает pay_url в Telegram и выбирает способ: из кошелька Kivix, через @CryptoBot, @xRocket, рублями по СБП или переводом криптовалюты на свой адрес Kivix. Для вас разницы нет: счёт всегда оплачивается одинаково — ровно на amount в asset, деньги приходят на баланс приложения, вы получаете событие invoice.paid. Комиссии провайдеров платит покупатель.

Если счёт истёк, пока покупатель платил провайдеру или переводил, деньги остаются у покупателя на балансе Kivix — счёт не оплачивается задним числом. Поэтому ставьте expires_in с запасом, если ждёте оплату переводом (сеть Bitcoin — до 30 минут).

Список счетов

Новые первыми. Фильтры: status, order_id; limit 1–100 (по умолчанию 20); starting_after — курсор.

for invoice in pay.invoices.iterate(status="paid"):   # страницы подгружаются сами
    print(invoice.order_id, invoice.amount)

for await (const invoice of pay.invoices.iterate({ status: "paid" })) {
  console.log(invoice.order_id, invoice.amount);
}

foreach ($pay->invoices->iterate('paid') as $invoice) {
    echo $invoice['order_id'], ' ', $invoice['amount'], PHP_EOL;
}

curl "https://kivix.cc/v1/invoices?status=paid&limit=50" -H "Authorization: Bearer $KIVIX_PAY_KEY"

Получить счёт

Найти по номеру заказа — GET /v1/invoices?order_id=1001 (в SDK: find_by_order / findByOrder).

Отменить счёт

Только пока он active. Оплаченный счёт отменить нельзя — вернётся 409 invoice_not_cancellable.

Приложение и баланс

Вывести накопленное на свой кошелёк — в боте: Kivix Pay → приложение → 💰 Вывести на кошелёк.