Создать аккаунт Кабинет
Все статьи Разработчикам

Как подключить приём криптоплатежей через API Ketmus

Один POST-запрос создаёт счёт и возвращает ссылку на оплату. Разбираем поля запроса, ответ и статусы счёта.

6 мин чтения

Приём платежей в Ketmus строится вокруг одной сущности — счёта. Вы создаёте счёт в своей валюте цены, Ketmus показывает плательщику страницу оплаты со списком доступных монет, отслеживает перевод в сети и сообщает вам о результате.

Шаг 1. Получите ключ API

Ключ создаётся в кабинете, в разделе «Мерчант» для каждого проекта отдельно. Передавайте его в заголовке Authorization: Bearer. Ключ даёт право создавать и читать счета проекта и не должен попадать в код фронтенда.

Шаг 2. Создайте счёт

Обязательное поле только одно — amount. Валюта цены по умолчанию USD. Остальные поля помогают связать счёт с вашим заказом и настроить поведение страницы оплаты.

curl -X POST https://app.ketmus.com/api/merchant/v1/invoices \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "currency": "USD",
    "order_id": "order-1024",
    "description": "Order #1024",
    "callback_url": "https://shop.example/webhooks/ketmus",
    "success_url": "https://shop.example/thanks",
    "fail_url": "https://shop.example/cart"
  }'

Необязательные поля: rail — сразу зафиксировать монету и сеть; rails — ограничить список доступных монет; lifetime_sec — время жизни счёта от 60 секунд до 30 дней; fee_payer — кто платит комиссию, merchant или payer; underpaid_coverage_bps — допустимая недоплата; metadata, payer_email, customer_id и return_url.

Повторный запрос с тем же order_id идемпотентен: вместо дубликата вы получите уже созданный счёт. Это позволяет безопасно повторять запрос при сетевых ошибках.

Шаг 3. Отправьте плательщика на pay_url

{
  "invoice": {
    "id": "7c7b4b2e-…",
    "status": "new",
    "pay_url": "https://app.ketmus.com/checkout/Xk3…",
    "price": { "amount": "49.9", "currency": "USD" },
    "payment": null,
    "available_rails": [{ "id": "usdt_tron", "asset": "USDT", "network": "tron", … }],
    "expires_at": "2026-10-26T13:00:00.000Z"
  }
}

В ответе приходит ссылка pay_url — на неё нужно перенаправить покупателя. На странице оплаты он выбирает монету из available_rails, получает адрес и точную сумму. После оплаты Ketmus вернёт его на success_url, при отмене или истечении срока — на fail_url.

Статусы счёта

  • new — счёт создан, плательщик ещё не выбрал монету.
  • pending — монета выбрана, ждём перевод в сети.
  • confirming — перевод найден, ждём подтверждений сети.
  • paid и paid_over — оплачен; второй статус означает переплату.
  • wrong_amount_waiting и wrong_amount — пришла неверная сумма; пока счёт не истёк, плательщик может доплатить.
  • expired и cancelled — срок истёк или счёт отменён через API.

Проверить статус можно запросом GET /api/merchant/v1/invoices/{id} или по order_id, но для рабочей интеграции надёжнее получать webhook-уведомления — о них следующая статья.

Читайте также