Получение

API-ключ: Payment

Возвращает текущее состояние инвойса. Формат ответа — тот же, что и при создании инвойса; объект payment появляется после выбора токена и сети.

Ответ (200 OK)

{
  "invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
  "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
  "status": "paid",
  "is_final": true,
  "is_test": false,
  "payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
  "order": {
    "external_id": "order-12345",
    "client_id": "customer-67890",
    "amount": "50.00",
    "currency": "USDT",
    "network": "TRC20"
  },
  "payment": {
    "currency": "USDT",
    "network": "TRC20",
    "chain_id": 728126428,
    "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "expected": "50.00",
    "address": "TLfGqSVPbET2KFczh3xb12Ja2RKfMCBPgp",
    "exchange_rate": "1.000000",
    "paid": "50.00",
    "remaining": "0",
    "fee": "0.50",
    "net": "49.50",
    "transfers": [
      {
        "tx_hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "amount": "50.00",
        "status": "confirmed",
        "created_at": 1739280712,
        "confirmed_at": 1739280912,
        "required_confirmations": 19,
        "estimated_confirmation_at": 1739280772,
        "explorer_url": "https://tronscan.org/#/transaction/abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
      }
    ]
  },
  "created_at": 1739280600,
  "updated_at": 1739280912,
  "expires_at": 1739284200,
  "completed_at": 1739280912
}

Поля payment

Когда объект payment присутствует, он содержит:

Поле	Тип	Описание
payment.currency	string	Символ криптоактива, выбранный для оплаты (например USDT, USDC)
payment.network	string	Код сети блокчейна (например ERC20, TRC20, BEP20, POLYGON, BASE, TON, SOL)
payment.chain_id	integer	Числовой идентификатор сети по правилам EIP-155, Tron или TON (например, 1 для основной сети Ethereum, 728126428 для Tron)
payment.contract_address	string?	On-chain идентификатор токена — адрес контракта в EVM и Tron, мастер-контракт жетона в TON, SPL-mint в Solana. Задан всегда: любой принимаемый актив — это стейблкоин на контракте, нативной монеты среди них нет.
payment.expected	string	Ожидаемая сумма в крипте, которую должен отправить клиент
payment.address	string?	Адрес, на который платит клиент. Пока инвойс в статусе awaiting_client, объекта payment в ответе нет целиком — то есть на неоплаченном инвойсе это поле не приходит как null, читать просто нечего
payment.exchange_rate	string?	Курс фиат → крипта, по которому посчитан expected
payment.paid	string?	Сумма подтверждённых входящих переводов
payment.remaining	string?	Оставшаяся сумма к доплате (expected - paid, не бывает отрицательной). Появляется после первого подтверждённого перевода
payment.fee	string?	Платформенная комиссия, удерживаемая из paid
payment.net	string?	Сумма к зачислению мерчанту (paid - fee)
payment.transfers	array?	Детали по каждому переводу — присутствует, когда обнаружён хотя бы один перевод on-chain. См. ниже.

Поля перевода

Каждый элемент массива payment.transfers[]:

Поле	Тип	Описание
tx_hash	string	Хэш on-chain транзакции (формат зависит от сети)
amount	string	Сумма перевода в крипте
status	string	confirming (ждём подтверждений) или confirmed
created_at	unix timestamp	Когда наш обработчик блоков впервые увидел перевод в обработанном блоке. Это время по часам нашего сервера, а не timestamp блока on-chain — они расходятся, если обработчик отставал. Используйте именно это поле (а не created_at инвойса верхнего уровня) в формуле «осталось секунд» ниже.
confirmed_at	unix timestamp?	Когда перевод достиг требуемого числа подтверждений. null, пока перевод ещё не подтверждён
required_confirmations	integer?	Сколько подтверждений нужно этому переводу, чтобы перейти в confirmed — зависит от USD-уровня его суммы. null на сетях с тегом финальности (BSC, Polygon, Solana), где мы ждём флаг finalized, а не считаем блоки
estimated_confirmation_at	unix timestamp?	Когда перевод предположительно достигнет required_confirmations. Вычисляется в момент обнаружения как transfer.created_at + required_confirmations × network_block_time. Значение фиксированное — не меняется от запроса к запросу и остаётся прежним при каждом опросе, пока перевод не перейдёт в confirmed (или пока не сменится USD-уровень его суммы). Чтобы получить «осталось секунд», считайте на стороне клиента: max(0, estimated_confirmation_at − now). null на сетях с тегом финальности (BSC, Polygon, Solana), где нет фиксированной цели по числу блоков.
explorer_url	string?	Прямая ссылка на эту транзакцию в обозревателе блоков сети (Tronscan / Etherscan / Tonviewer и т. п.). null, если для сети не настроен публичный обозреватель. Можно выводить как кликабельную ссылку без изменений — преобразовывать её не нужно.

Статусы инвойса

У каждого инвойса есть поле status. Одно и то же значение приходит в ответе API, в потоке SSE на странице оплаты и в вебхуке — источник один. Таблица ниже — справочник по статусам: когда статус наступает, терминальный он или нет и при каком условии возникает. Схему переходов и оба потока создания смотрите в разделе Платёжный процесс.

Терминальный статус — конечный: инвойс на нём закрывается и больше не меняется. Терминальных пять — paid, paid_over, underpaid, expired, cancelled.

Статус	Терминальный	Описание
awaiting_client	Нет	Стартовый статус любого инвойса. Клиент ещё не выбрал токен/сеть, поэтому адрес для оплаты не назначен. Отменить инвойс можно только в этом статусе
awaiting_payment	Нет	Адрес назначен, ожидает входящий перевод
confirming	Нет	Перевод виден в блокчейне и набирает число подтверждений, положенное его сумме
underpaid_waiting	Нет	Получена частичная оплата, ожидает остаток (только при allow_multiple_payments = true)
paid	Да	Ожидаемая сумма получена полностью — либо в пределах допуска по недоплате, заданного в проекте
paid_over	Да	Полученная сумма превышает ожидаемую (зачисляется полностью)
underpaid	Да	Инвойс закрылся с недоплатой: либо истёк, не добрав до ожидаемой суммы, либо единственный платёж не покрыл её при allow_multiple_payments = false
expired	Да	Инвойс истёк без оплаты, или истекло окно выбора токена (фиатный поток)
cancelled	Да	Инвойс отменён мерчантом (только из статуса awaiting_client)

Ошибки

См. Коды ошибок — полный каталог. URI в поле type каждой ошибки ведёт сразу на нужную строку.