API Reference v1

Создание счёта

Создаёт счёт на оплату и возвращает ссылку на платёжную страницу и реквизиты.

POSTapp.ketmus.com/api/merchant/v1/invoices

Создаёт новый счёт. Если передан rail, адрес для оплаты выдаётся сразу и его можно показать в своём интерфейсе. Без rail клиент выберет монету на платёжной странице pay_url.

Параметры

amountnumber | stringобязательный: Сумма счёта в валюте currency. Больше 0, не более 1 000 000 000.
currencystring: Валюта цены: USD, USDT, EUR, RUB, UAH, KZT, TRY, GBP. По умолчанию USD.
order_idstring: Ваш номер заказа, до 64 символов. По нему можно найти счёт и избежать дубликатов.
descriptionstring: Описание, которое увидит клиент на платёжной странице. До 300 символов.
metadataobject: Произвольные данные (например, user_id). Возвращаются в ответах и вебхуках.
railstring: Сразу выбрать монету и сеть, например usdt_tron. Список — в Монеты и сети.
railsstring[]: Ограничить список монет, из которых выбирает клиент.
lifetime_secinteger: Время жизни счёта в секундах: от 300 (5 минут) до 86 400 (24 часа). По умолчанию — из настроек магазина (обычно 3600).
fee_payerstring: Кто платит комиссию: merchant или payer. По умолчанию — из настроек магазина.
underpaid_coverage_bpsinteger: Допустимая недоплата в базисных пунктах (0–5000), при которой счёт всё равно считается оплаченным.
callback_urlstring: URL для вебхуков этого счёта. Если не передан — используется URL из настроек магазина.
return_urlstring: Куда вернуть клиента по кнопке «Вернуться в магазин».
success_urlstring: Куда перенаправить клиента после успешной оплаты.
fail_urlstring: Куда перенаправить клиента, если счёт истёк или отменён.
payer_emailstring: Email клиента для чека и связи.
customer_idstring: Ваш идентификатор клиента, до 120 символов.

Неизвестные параметры отклоняются с ошибкой 400 invalid — это защищает от опечаток в названиях полей.

Пример запроса

curl -X POST "https://app.ketmus.com/api/merchant/v1/invoices" \
  -H "Authorization: Bearer $KETMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25,
    "currency": "USD",
    "order_id": "ORDER-1042",
    "description": "Подписка Pro на 1 месяц",
    "rail": "usdt_tron",
    "metadata": {
      "user_id": "u_731"
    },
    "callback_url": "https://shop.example.com/webhooks/ketmus",
    "success_url": "https://shop.example.com/orders/1042?paid=1",
    "fail_url": "https://shop.example.com/orders/1042?failed=1"
  }'

Ответ

HTTP 201 Created. Объект счёта содержит также available_rails — монеты, которыми можно оплатить этот счёт.

{
  "invoice": {
    "type": "invoice",
    "id": "8f0c6a52-3f7e-4b8e-9d61-2c4b0f8a1e7d",
    "order_id": "ORDER-1042",
    "status": "pending",
    "is_final": false,
    "late_payment": false,
    "price": {
      "amount": "25",
      "currency": "USD"
    },
    "payment": {
      "rail": "usdt_tron",
      "asset": "USDT",
      "network": "tron",
      "address": "TQ7nX4yVh3cE9v5G2kRZb8aWm1pLd6sFJt",
      "memo": null,
      "amount_due": "25.31",
      "amount_received": "0",
      "amount_confirmed": "0",
      "late_amount": "0",
      "rate": "1",
      "txids": []
    },
    "fee": {
      "bps": 125,
      "payer": "payer",
      "amount": "0",
      "merchant_amount": "0"
    },
    "pay_url": "https://app.ketmus.com/checkout/inv_5Kq2ZtR8wLmA",
    "metadata": {
      "user_id": "u_731"
    },
    "created_at": "2026-11-03T10:15:00.000Z",
    "expires_at": "2026-11-03T11:15:00.000Z",
    "paid_at": null,
    "public_id": "inv_5Kq2ZtR8wLmA",
    "description": "Подписка Pro на 1 месяц",
    "lifetime_sec": 3600,
    "underpaid_coverage_bps": 0,
    "refresh_count": 0,
    "return_url": "https://shop.example.com/orders/1042",
    "success_url": "https://shop.example.com/orders/1042?paid=1",
    "fail_url": "https://shop.example.com/orders/1042?failed=1",
    "payer_email": null,
    "customer_id": null,
    "payment_uri": null,
    "explorer_address_url": "https://tronscan.org/#/address/TQ7nX4yVh3cE9v5G2kRZb8aWm1pLd6sFJt",
    "available_rails": [
      {
        "id": "usdt_tron",
        "asset": "USDT",
        "network": "tron",
        "label": "USDT",
        "network_label": "Tron (TRC-20)",
        "icon": "/coins/tether.svg",
        "confirmations": 20
      },
      {
        "id": "ton",
        "asset": "TON",
        "network": "ton",
        "label": "Toncoin",
        "network_label": "TON",
        "icon": "/coins/toncoin.svg",
        "confirmations": 1
      }
    ]
  }
}

Счёт без выбранной монеты

Если rail не передан, поле payment равно null, а статус — new. Адрес появится, когда клиент выберет монету на pay_url:

{
  "invoice": {
    "type": "invoice",
    "id": "8f0c6a52-3f7e-4b8e-9d61-2c4b0f8a1e7d",
    "order_id": "ORDER-1042",
    "status": "new",
    "is_final": false,
    "late_payment": false,
    "price": {
      "amount": "25",
      "currency": "USD"
    },
    "fee": null,
    "pay_url": "https://app.ketmus.com/checkout/inv_5Kq2ZtR8wLmA",
    "metadata": {
      "user_id": "u_731"
    },
    "created_at": "2026-11-03T10:15:00.000Z",
    "expires_at": "2026-11-03T11:15:00.000Z",
    "paid_at": null,
    "public_id": "inv_5Kq2ZtR8wLmA",
    "description": "Подписка Pro на 1 месяц",
    "lifetime_sec": 3600,
    "underpaid_coverage_bps": 0,
    "refresh_count": 0,
    "return_url": "https://shop.example.com/orders/1042",
    "success_url": "https://shop.example.com/orders/1042?paid=1",
    "fail_url": "https://shop.example.com/orders/1042?failed=1",
    "payer_email": null,
    "customer_id": null,
    "payment_uri": null,
    "explorer_address_url": null,
    "payment": null
  }
}

Поля объекта счёта

idstring: Идентификатор счёта (UUID). Используйте в запросах к API.
public_idstring: Публичный идентификатор для ссылки на оплату.
statusstring: Текущий статус. → Статусы счёта
is_finalboolean: true, если статус окончательный и больше не изменится.
priceobject: Цена счёта: amount и currency.
paymentobject | null: Реквизиты и суммы в выбранной монете. null, пока монета не выбрана.
payment.addressstring: Адрес, на который нужно отправить перевод.
payment.memostring | null: Memo или destination tag (для XRP). Без него платёж не будет зачислен.
payment.amount_duestring: Сумма к оплате в монете, включая комиссию, если её платит клиент.
payment.amount_receivedstring: Сколько уже пришло, включая неподтверждённые транзакции.
payment.amount_confirmedstring: Сколько пришло с нужным числом подтверждений.
payment.txidsstring[]: Хеши транзакций по счёту.
feeobject | null: Комиссия: bps, payer, amount и merchant_amount — сумма к зачислению магазину.
pay_urlstring: Ссылка на платёжную страницу Ketmus. Именно её отправляйте покупателю — для любой монеты и для СБП.
payment_uristring | null: URI для QR-кода в вашем собственном интерфейсе (bitcoin:, ton:, ethereum: и т. д.). Для СБП — прямая ссылка банка https://qr.nspk.ru/…: не отправляйте её покупателю вместо pay_url.
sbpobject: Только для СБП: amount_rub — точная сумма в рублях, pay_until — до какого времени действует QR-код.
expires_atstring: Когда истекает счёт (ISO 8601, UTC).
paid_atstring | null: Когда счёт был оплачен.

Создание счёта

#Параметры

#Пример запроса

#Ответ

#Счёт без выбранной монеты

#Поля объекта счёта

Параметры

Пример запроса

Ответ

Счёт без выбранной монеты

Поля объекта счёта