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-политика

    Инвойсы: статусы и жизненный цикл

    СтатусЗначениеФинальный
    activeЖдёт оплатынет
    payingПлатёж найден в блоке, ждёт подтвержденийнет
    partially_paidПодтверждена часть суммы, можно доплатить на тот же адреснет
    paidОплачен полностьюда
    overpaidОплачен с излишком: overpaid: true, overpaid_amountда
    expiredСрок истёк без полной оплатыда
    canceledОтменён мерчантомда
    Пример
    active ──платёж в блоке──▶ paying ──подтверждён, хватает──▶ paid / overpaid
      │                          │
      │                          ├─подтверждён, не хватает──▶ partially_paid ──доплата──▶ paying
      │                          └─reorg, транзакция пропала──▶ active / partially_paid
      ├─DELETE──▶ canceled
      └─срок истёк──▶ expired          (partially_paid тоже истекает)

    Правила:

    1. Обнаружение. Watcher видит перевод на адрес инвойса. Если монета совпадает с asset, а инвойс в active или partially_paid, инвойс переходит в paying и уходит invoice_paying.
    2. Подтверждение. После required_confirmations подтверждений (TRON 19, TON и Solana 1, Simnet 3, от 5000 вдвое больше) сумма зачитывается в paid_amount, баланс мерчанта пополняется. На mainnet платёж от порога AML (по умолчанию 1000) перед зачислением ждёт проверки адреса отправителя, если в развёртывании включён AML-провайдер. Пока проверка не прошла, инвойс остаётся paying и invoice_paid не уходит: обычно это секунды, при недоступности провайдера дольше. Платёж с высоким риском замораживается до решения оператора: invoice_paid придёт, только если оператор его зачислит.
    3. Допуск недоплаты. Инвойс считается оплаченным, если paid_amount ≥ pay_amount − допуск. Допуск задаётся в настройках приложения (по умолчанию 0.5 %, от 0 до 2 %), но не меньше 0.5 монеты, если он не нулевой. Пример: при допуске 0.5 % инвойс на 10 USDT закрывается платежом от 9.5 USDT.
    4. Частичная оплата. Если подтверждено меньше нужного и других платежей в пути нет: при включённой в настройках «частичной оплате» (по умолчанию включена) статус partially_paid и событие invoice_partially_paid, иначе инвойс возвращается в active. Доплата идёт на тот же адрес.
    5. Истечение. Expirer раз в 5 секунд закрывает открытые инвойсы с прошедшим expires_at. Инвойс, у которого есть платёж в блоке без нужных подтверждений, ждёт этих подтверждений. При истечении частично оплаченного инвойса его поступления становятся unmatched: деньги остаются на балансе мерчанта, возврат плательщику делается вручную.
    6. Поздний платёж на адрес истёкшего инвойса. С настройкой «принимать просроченные» и в пределах 24 часов после expires_at платёж зачитывается в инвойс, пока его адрес не выдан другому инвойсу (по умолчанию через час после закрытия, см. правило 11). Если суммы хватает, инвойс переходит в paid с событием invoice_paid. Если не хватает, статус остаётся expired с событием payment_late. Без настройки или позже 24 часов платёж становится unmatched с событием payment_late.
    7. Чужая монета (например USDC на инвойс в USDT): unmatched, событие payment_unexpected, статус инвойса не меняется.
    8. Платёж на закрытый инвойс (paid, overpaid, canceled): unmatched, событие payment_unexpected.
    9. Комиссия с unmatched. С каждого такого поступления берётся та же комиссия: 1 %, минимум 0.1. Остаток зачисляется на баланс мерчанта. Возвраты плательщикам не автоматические: мерчант делает их сам выводом.
    10. Дубли. Поступление идентифицируется по (сеть, txid, log_index), повторная обработка того же события ничего не меняет.
    11. Повторное использование адреса. После закрытия инвойса (paid, overpaid, expired, canceled) его адрес возвращается в пул через паузу: по умолчанию 1 час, точное значение задаёт оператор. Пока адрес не выдан следующему инвойсу, платежи на него относятся к вашему инвойсу по правилам 6 и 8. После выдачи платёж на этот адрес, равный сумме нового инвойса, считается его оплатой, а новый инвойс может принадлежать другому мерчанту. Платёж на другую сумму никому не зачисляется автоматически: его разбирает оператор шлюза и относит к вашему инвойсу вручную, это занимает время. Показывайте плательщику срок инвойса и создавайте новый инвойс для каждой оплаты.
    НазадPOST/sandbox/eventsДальше Выводы: статусы