Invoices API

Все мерчант-эндпоинты с примерами: создание, листинг, получение, отмена, QR-коды, а также events и payouts.

Полный тур по мерчант REST API. Интерактивная схема всех полей: API Reference. Все денежные значения — строки-десятичные ("49.99"), все таймстемпы — ISO 8601 UTC.

Base URL: https://api.zerokyc-payments.com. Каждый запрос авторизуется ключом:

Authorization: Bearer pk_live_...

Ключи pk_test_… работают на обоих и оперируют строго sandbox-инвойсами.

Создать инвойс

curl -X POST https://api.zerokyc-payments.com/v1/invoices \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-create" \
  -d '{
    "amount": "49.99",
    "base_currency": "USD",
    "payment_currency": "any",
    "order_id": "order-1042",
    "description": "VPS Cloud Hosting 1 Month",
    "ttl_minutes": 360,
    "webhook_url": "https://api.merchant.com/zkp-webhook",
    "success_url": "https://merchant.com/orders/1042/success",
    "metadata": { "customer_id": "cust_8821" }
  }'

Поле	Тип	Заметки
`amount`	строка, обязательна	Десятичная строка > 0
`base_currency`	строка	`USD` (по умолчанию), `EUR`, `RUB` или id актива вроде `BTC` — инвойс сразу в крипте
`payment_currency`	строка	`any` (монету выбирает покупатель) или id актива вроде `USDT_TRON`
`order_id`	строка ≤ 255	Ваш идентификатор; возвращается в вебхуках
`description`	строка ≤ 500	Видно покупателю
`ttl_minutes`	int	По умолчанию 360, диапазон 10–4320
`webhook_url`	строка ≤ 2000	Переопределение эндпоинта из кабинета для этого инвойса
`success_url`	строка ≤ 2000	Редирект покупателя после подтверждения
`metadata`	объект	Произвольные пары ключ-значение; возвращаются везде

Ответ 201 возвращает полный инвойс (ниже). Заголовок Idempotency-Key (≤120 символов) делает ретраи безопасными — семантика.

Объект инвойса

{
  "id": "inv_live_9x8aL2mP0k1q",
  "order_id": "order-1042",
  "amount": "49.99",
  "base_currency": "USD",
  "payment_currency": "any",
  "status": "pending",
  "ttl_minutes": 360,
  "expires_at": "2026-09-13T19:00:00Z",
  "created_at": "2026-09-13T13:00:00Z",
  "checkout_url": "https://app.zerokyc-payments.com/pay/inv_live_9x8aL2mP0k1q",
  "options": [
    {
      "asset": "USDT",
      "network": "tron",
      "payment_address": "TYDzsYUEpvnYmQk4zGP9sWWcTEd2MiAtW6",
      "amount_crypto": "49.99",
      "rate": "1.0",
      "status": "open",
      "window_low": null,
      "window_high": null,
      "payment_url_extra": null,
      "confirmed_tx_hash": null
    }
  ],
  "observations": [],
  "paid_amount": null,
  "paid_asset": null,
  "metadata": { "customer_id": "cust_8821" }
}

Помимо очевидных полей: options[] (по одному на включённый актив — статусы и окна уникальных сумм разобраны в жизненном цикле), observations[] (сырые наблюдения с цепи), а после подтверждения — paid_amount / paid_asset / confirmed_tx_hash у опции.

Получить инвойс

curl https://api.zerokyc-payments.com/v1/invoices/inv_live_9x8aL2mP0k1q \
  -H "Authorization: Bearer pk_live_..."

Всегда авторитетный источник — при сомнениях доверяйте ему, а не payload вебхука.

Листинг инвойсов

curl "https://api.zerokyc-payments.com/v1/invoices?status=pending&limit=50" \
  -H "Authorization: Bearer pk_live_..."

Пагинация курсорная и стабильная:

cursor = None
while True:
    query = f"limit=100{f'&cursor={cursor}' if cursor else ''}"
    page = get(f"/v1/invoices?{query}")
    process(page["data"])
    if not page["has_more"]:
        break
    cursor = page["next_cursor"]

Отменить инвойс

curl -X POST https://api.zerokyc-payments.com/v1/invoices/inv_live_9x8aL2mP0k1q/cancel \
  -H "Authorization: Bearer pk_live_..."

Разрешено в статусе pending без замеченных платежей; срабатывает invoice.canceled. Уже подтверждённые инвойсы вернут 400 invalid_request.

QR-код платежа

curl "https://api.zerokyc-payments.com/v1/invoices/inv_live_9x8aL2mP0k1q/qr?asset=USDT_TRON&format=svg" \
  -H "Authorization: Bearer pk_live_..." -o qr.svg

asset — API id актива (USDT_TRON, TRX, USDT_ARBITRUM, BTC, LTC, DOGE, BCH, XRP, NEAR, SOL, USDT_SOL, USDC_SOL, TON, ETH, BNB, USDT_BSC, … — полная таблица в Сетях); format — png (по умолчанию) или svg. QR кодирует payment URI, включая memo для TON, где он нужен.

Events

GET /v1/events — ваш журнал событий: фильтры type (например payment.confirmed) и created_after, та же курсорная пагинация. Включает типы только-для-журнала вроде invoice.created. Payload вебхуков разобран в справочнике вебхуков.

Платформенные эндпоинты (без авторизации)

GET /v1/ping — {"status": "ok", "service": "zerokyc-pay-api", "chain_mode": "..."} — для uptime-проверок.
GET /v1/plans — тарифные планы витрины.
GET /v1/site-config — публичная конфигурация сайта (контакты, соцсети, баннер).