Ketmus
Esc

Начало работы

Как работает интеграция

Жизненный цикл платежа: от создания счёта до зачисления средств на баланс магазина.

Схема платежа

  1. 1

    Ваш сервер создаёт счёт

    Вы отправляете POST /invoices с суммой, валютой цены и номером заказа. Ketmus возвращает объект счёта и ссылку pay_url.

  2. 2

    Клиент выбирает монету

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

  3. 3

    Ketmus выдаёт адрес

    Для счёта создаётся отдельный адрес, а сумма в криптовалюте фиксируется по текущему курсу. Счёт переходит в статус pending.

  4. 4

    Клиент отправляет перевод

    Как только транзакция появляется в сети, счёт переходит в confirming и ждёт нужное число подтверждений.

  5. 5

    Платёж подтверждён

    Счёт получает статус paid (или paid_over при переплате), сумма за вычетом комиссии зачисляется на баланс магазина.

  6. 6

    Вы получаете вебхук

    При каждом изменении статуса Ketmus отправляет подписанный POST-запрос на ваш URL. По событию invoice.paid вы выдаёте товар.

Источник истины

Не выдавайте товар по факту возврата клиента на success_url — пользователь может открыть этот адрес вручную. Решение о выдаче принимайте только по вебхуку с проверенной подписью или после запроса информации о счёте с вашего сервера.

Важно

Обрабатывайте вебхуки идемпотентно: одно и то же событие может прийти повторно. Сохраняйте delivery_id и не выдавайте товар дважды для одного order_id.

Суммы и курс

Цена счёта задаётся в одной из валют: USD, USDT, EUR, RUB, UAH, KZT, TRY, GBP. После выбора монеты Ketmus пересчитывает её в сумму к оплате payment.amount_due по актуальному курсу и фиксирует курс в поле payment.rate на всё время жизни счёта.

Все суммы в криптовалюте передаются строками в десятичном виде, например "0.00041", чтобы не терять точность. Не преобразуйте их в числа с плавающей точкой при сохранении в базу.

Комиссия

Комиссия задаётся в базисных пунктах (bps, 100 bps = 1%). Её может оплачивать магазин или клиент — параметр fee_payer. Если комиссию платит клиент, она добавляется к сумме к оплате; если магазин — удерживается из зачисления. Итоговые суммы видны в объекте fee счёта.

Недоплата, переплата и поздние платежи

  • Недоплата. Если пришло меньше нужной суммы, счёт переходит в wrong_amount_waiting и ждёт доплаты до истечения срока. Параметр underpaid_coverage_bps позволяет считать счёт оплаченным при небольшой недоплате, например 50 bps = 0,5%.
  • Переплата. Если пришло больше, счёт получает статус paid_over, а на баланс зачисляется вся полученная сумма.
  • Поздний платёж. Если перевод пришёл после истечения счёта, Ketmus всё равно зачислит его и отправит событие invoice.late_payment.