Принимайте криптоплатежи через Merchant API
Один POST-запрос создаёт счёт и возвращает ссылку на оплату. О смене статуса ваш сервер узнаёт из подписанного webhook.
Быстрый старт
Три шага от регистрации до первого оплаченного счёта.
Получите ключ
В кабинете, в разделе «Мерчант», у каждого проекта свой API-ключ. Его можно перевыпустить в любой момент.
Создайте счёт
POST /invoices с суммой в валюте цены. В ответе — pay_url, на который нужно отправить плательщика.
Получите webhook
На callback_url приходит POST при каждой смене статуса. Проверьте подпись и отметьте заказ оплаченным.
Авторизация
Все запросы идут на базовый адрес ниже и передают ключ проекта в заголовке Authorization: Bearer. Тело запросов и ответов — JSON.
https://app.ketmus.com/api/merchant/v1- Ключ — только на сервере. Не размещайте его в коде сайта или мобильного приложения.
- Повторный запрос с тем же order_id возвращает уже созданный счёт, а не дубликат.
- Обязательное поле счёта одно — 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",
"callback_url": "https://shop.example/webhooks/ketmus",
"success_url": "https://shop.example/thanks"
}'{
"invoice": {
"id": "7c7b4b2e-…",
"status": "new",
"pay_url": "https://app.ketmus.com/checkout/Xk3…",
"price": { "amount": "49.9", "currency": "USD" },
"expires_at": "2026-10-26T13:00:00.000Z"
}
}Методы API
Пути указаны относительно базового адреса.
| Метод | Путь | Назначение |
|---|---|---|
| POST | /invoices | Создать счёт |
| GET | /invoices | Список счетов проекта |
| GET | /invoices/{id} | Счёт со статусом и платежами |
| POST | /invoices/{id}/cancel | Отменить неоплаченный счёт |
| POST | /static-addresses | Выдать постоянный адрес для пополнений |
| GET | /static-addresses | Список выданных адресов |
| GET | /balance | Баланс проекта по монетам |
| GET | /rails | Доступные монеты и сети |
| GET | /rates | Текущие курсы |
| GET | /me | Данные проекта, которому принадлежит ключ |
Webhook-уведомления
Если при создании счёта указан callback_url, Ketmus отправляет на него POST при каждой смене статуса. Тело — JSON счёта и поле event.
- Заголовки x-ketmus-event, x-ketmus-timestamp и x-ketmus-signature.
- Подпись — HMAC-SHA512 от строки «timestamp.body» с секретом проекта. Проверяйте по сырому телу запроса.
- Ответьте кодом 2xx за 10 секунд. Иначе доставка повторится через 1, 5 и 30 минут, затем через 2, 6 и 24 часа.
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verifyKetmus(rawBody: string, header: string, secret: string) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const age = Math.abs(Date.now() / 1000 - Number(parts.t))
if (!parts.t || !parts.v1 || age > 300) return false
const expected = createHmac('sha512', secret).update(`${parts.t}.${rawBody}`).digest('hex')
return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}Лимиты и ошибки
На один ключ — до 300 запросов в минуту. При превышении API отвечает 429 с кодом rate_limited. Все ошибки приходят в одном формате: объект error с машиночитаемым code и текстом message.
HTTP/1.1 429 Too Many Requests
{ "error": { "code": "rate_limited", "message": "…" } }Нужна помощь с интеграцией?
Напишите в поддержку в Telegram — поможем разобраться с API и webhook.