Paylane
ДокументацияСтатус
ВойтиСоздать аккаунт

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

  • Обзор
  • Адреса и окружения
  • Авторизация
  • Формат ответа
  • Ошибки
  • Идемпотентность
  • Лимиты

Методы API

  • Методы
  • GET/me
  • GET/currencies
  • POST/invoices
  • GET

Справочник

  • Инвойсы: статусы и жизненный цикл
  • Выводы: статусы
  • Вебхуки
  • Проверка подписи
  • Публичный API страницы оплаты
  • Testnet, mainnet и Simnet

Документы

  • Оферта для мерчантов
  • Политика конфиденциальности
  • AML/KYC-политика
Разделы: Вебхуки

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

  • Обзор
  • Адреса и окружения
  • Авторизация
  • Формат ответа
  • Ошибки

Paylane

Paylane: приём платежей в стейблкоинах

Продукт

ДокументацияСтатусВойтиСоздать аккаунт

Документы

ОфертаКонфиденциальностьAML-политика
/invoices
  • GET/invoices/{id}
  • DELETE/invoices/{id}
  • GET/balance
  • POST/withdrawals
  • GET/withdrawals/{id}
  • GET/stats
  • POST/webhooks/test
  • POST/webhooks/{update_id}/resend
  • POST/sandbox/invoices/{id}/pay
  • POST/sandbox/events
  • Sandbox и тестовые сценарии
    Идемпотентность
  • Лимиты
  • Методы API

    • Методы
    • GET/me
    • GET/currencies
    • POST/invoices
    • GET/invoices
    • GET/invoices/{id}
    • DELETE/invoices/{id}
    • GET/balance
    • POST/withdrawals
    • GET/withdrawals/{id}
    • GET/stats
    • POST/webhooks/test
    • POST/webhooks/{update_id}/resend
    • POST/sandbox/invoices/{id}/pay
    • POST/sandbox/events

    Справочник

    • Инвойсы: статусы и жизненный цикл
    • Выводы: статусы
    • Вебхуки
    • Проверка подписи
    • Публичный API страницы оплаты
    • Testnet, mainnet и Simnet
    • Sandbox и тестовые сценарии

    Документы

    • Оферта для мерчантов
    • Политика конфиденциальности
    • AML/KYC-политика

    Вебхуки

    Сервер отправляет POST на webhook_url приложения (задаётся в настройках приложения в кабинете). Смена уже заданного URL требует код 2FA, если 2FA включена, и вступает в силу через час: на email аккаунта приходит письмо со ссылкой отмены. Первая установка URL применяется сразу.

    Типы событий

    update_typeКогдаpayload
    invoice_payingПлатёж найден в блокеинвойс + confirmations: 0, required_confirmations, txid
    invoice_paidИнвойс оплачен (paid или overpaid). Включено всегдаинвойс + txid
    invoice_partially_paidПодтверждена часть суммыинвойс + txid
    invoice_expiredСрок истёкинвойс
    invoice_canceledОтменён через API или кабинетинвойс
    payment_lateПлатёж на истёкший инвойсинвойс + txid + deposit
    payment_unexpectedЧужая монета или платёж на закрытый инвойсинвойс + txid + deposit
    withdrawal_completedВывод подтверждён: все его переводывывод, txid и txids заполнены
    withdrawal_failedВывод отклонён сетью или операторомвывод с error
    testPOST /webhooks/test или кнопка в кабинете. Включено всегда{"message": "Тестовый вебхук Paylane"}

    «Инвойс» и «вывод» здесь имеют те же поля, что ответы GET /invoices/{id} (без transactions) и GET /withdrawals/{id}. Какие события получать, выбирается в настройках приложения. Новое приложение подписано на все, invoice_paid и test отключить нельзя.

    Тело запроса

    Для удобства JSON выше отформатирован. На проводе тело компактное, ключи отсортированы, кириллица не экранируется.

    Заголовки

    ЗаголовокЗначение
    Content-Typeapplication/json
    Paylane-SignatureПодпись, hex
    Paylane-Signature-NextТолько 24 часа после смены секрета в кабинете: подпись новым секретом. Основные заголовки в это время подписаны старым
    Paylane-TimestampВремя этой попытки доставки, unix-секунды
    Paylane-Signature-V2Подпись строки timestamp + "." + тело, тот же алгоритм и ключ. Защищает от повтора перехваченного запроса
    Paylane-Signature-V2-NextКак Paylane-Signature-Next, для подписи с временем
    User-AgentPaylane-Webhooks/1

    Доставка

    • Успех: ответ 2xx за 10 секунд. Тело ответа не читается, сохраняются только первые 1 КБ для журнала.
    • Любой другой ответ, редирект (редиректы не выполняются), таймаут или ошибка соединения означают неудачу.
    • 7 попыток: сразу, затем через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч после предыдущей неудачи, всего около 33 часов. После седьмой неудачи событие получает статус failed. В журнале вебхуков кабинета видны все попытки, там же кнопка повтора.
    • Порядок: события одного приложения доставляются по очереди. Пока раннее событие не доставлено и у него меньше 3 попыток (около 6 минут), следующие ждут. После третьей неудачи оно повторяется по своему расписанию, а очередь идёт дальше: при коротком сбое порядок сохраняется, одно сломанное событие не держит остальные. Поэтому порядок прихода не гарантирован: опирайтесь на update_id и статус в теле, а не на очерёдность.
    • Смена секрета: «Сгенерировать новый секрет» в настройках приложения. 24 часа Paylane-Signature подписан старым секретом, Paylane-Signature-Next новым. Добавьте новый секрет на сервер, проверяя оба (SDK: parse_webhook(body, signature, [new_secret, old_secret])), затем «Завершить смену сейчас» или дождитесь конца срока.
    • Доставка «хотя бы один раз» (at-least-once). Одно событие может прийти больше одного раза: например, ваш сервер ответил 200 позже 10 секунд, соединение оборвалось после обработки, вы нажали «Повторить» в кабинете. Обработчик должен быть идемпотентным.
    • update_id растёт монотонно в пределах приложения. Повторная доставка приходит с тем же , тем же телом и тем же (это время события, а не попытки). Дедуплицируйте по : сохраните обработанные id и отвечайте 200 на повтор, ничего не делая.
    НазадВыводы: статусыДальше Проверка подписи
    update_id
    request_date
    update_id
  • URL только HTTPS. HTTP разрешён только приложениям в testnet-режиме.
  • Адрес должен быть публичным: имя, которое ведёт в частную сеть, на localhost или link-local адрес, не сохраняется, а попытка доставки на него завершается ошибкой.
  • Защита от повтора: проверяйте Paylane-Signature-V2 и отклоняйте запрос, если Paylane-Timestamp отличается от вашего времени больше чем на 5 минут. Повторная попытка доставки приходит с новым временем и новой подписью. В SDK: verify_webhook_fresh(body, headers, secret) и verifyWebhookFresh(body, headers, secret).
  • Отвечайте 200 сразу, а тяжёлую обработку делайте асинхронно. При сомнении в данных запросите GET /invoices/{id}.
  • Ответ
    {
      "update_id": 88,
      "update_type": "invoice_paid",
      "request_date": "2026-11-05T10:07:41Z",
      "payload": {
        "invoice_id": 10452,
        "status": "paid",
        "amount": "100.00",
        "currency": "USDT",
        "asset": "USDT",
        "network": "tron",
        "address": "TGzz8gjYiYRqpfmDwnLxfgPuLVNmpCswVp",
        "pay_amount": "100.00",
        "paid_amount": "100.00",
        "fee": "1.00",
        "fee_payer": "merchant",
        "pay_url": "https://pay.<домен>/i/Xq3vN8kT2pLmA9sd",
        "description": "Заказ №5512",
        "payload": "order-5512",
        "testnet": false,
        "created_at": "2026-11-05T10:00:00Z",
        "expires_at": "2026-11-05T11:00:00Z",
        "paid_at": "2026-11-05T10:07:41Z",
        "txid": "9c1e5b0d7a2f4e6c8b3a1d0e9f8c7b6a5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a"
      }
    }
    `invoice_paying`
    {
      "update_id": 87,
      "update_type": "invoice_paying",
      "request_date": "2026-11-05T10:06:58Z",
      "payload": {
        "invoice_id": 10452, "status": "paying", "amount": "100.00", "pay_amount": "100.00", "paid_amount": "0.00",
        "...": "остальные поля инвойса",
        "confirmations": 0, "required_confirmations": 19,
        "txid": "9c1e5b0d7a2f4e6c8b3a1d0e9f8c7b6a5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a"
      }
    }
    `payment_unexpected` (USDC пришёл на инвойс в USDT)
    {
      "update_id": 91,
      "update_type": "payment_unexpected",
      "request_date": "2026-11-05T10:30:12Z",
      "payload": {
        "invoice_id": 10452, "status": "paid", "paid_amount": "100.00",
        "...": "остальные поля инвойса",
        "txid": "4be0c2d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1",
        "deposit": {"txid": "4be0c2d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1", "amount": "15.00", "asset": "USDC"}
      }
    }
    `withdrawal_failed`
    {
      "update_id": 95,
      "update_type": "withdrawal_failed",
      "request_date": "2026-11-05T12:40:00Z",
      "payload": {
        "withdrawal_id": 381, "status": "rejected", "amount": "250.00", "fee": "1.00", "net_amount": "249.00",
        "currency": "USDT", "network": "tron", "address": "TGzz8gjYiYRqpfmDwnLxfgPuLVNmpCswVp", "memo": null,
        "txid": null, "txids": [], "error": "Отклонено оператором", "created_at": "2026-11-05T12:00:00Z"
      }
    }