Чтение депозита

API-ключ: Payment

Читает один депозит по идентификатору pcd_ в любом состоянии. Идентификатор, полученный из вебхука payment_channel.deposit.confirming, открывается здесь сразу, поэтому хранить payload вебхука только ради последующего поиска не нужно.

Ответ (200 OK)

{
  "id": "pcd_8ScRvL4jNq2XkB7mTfZdWu",
  "payment_channel_id": "pc_2QhKZv6mRt9WdA3nYpLbXf",
  "project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
  "payment_channel_external_id": "customer-42",
  "status": "confirmed",
  "is_final": true,
  "is_test": false,
  "currency": "USDT",
  "network": "TRC20",
  "chain_id": 728126428,
  "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "gross": "100",
  "fee": "1",
  "net": "99",
  "applied_fee_percent": 1.0,
  "customer_fee_percent": 0,
  "tx_hash": "9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25",
  "transfer_id": "9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25:41a614f803b6fd780986a42c78ec9c7f77e6ded13c:41c9f6a2b7d0138e54ca3b91f6072ed48a5c1e93b7:0",
  "source_address": "TW9s4RkAqBnLpVdX2ChYzUeGm7QfKt3NbZ",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "block_height": 68421905,
  "first_included_block_timestamp": 1767225900,
  "explorer_url": "https://tronscan.org/#/transaction/9f4c1b7e30ad52c8ef6a1d84b0c39f27a5e6d138f4b90c72ae51d63b8407fc25",
  "created_at": 1767225870,
  "updated_at": 1767225930,
  "confirmed_at": 1767225930
}

Поля

Поле	Значение
id	Идентификатор депозита (pcd_…). По нему выполняется дедупликация.
payment_channel_id, payment_channel_external_id	Канал, принявший платёж, и заданный вами идентификатор этого канала.
status	confirming, reorged или confirmed.
is_final	true только для confirmed.
currency, network, chain_id, contract_address	Какой токен пришёл и куда. contract_address — идентификатор токена в сети: адрес контракта в EVM и Tron, мастер-контракт жетона в TON, SPL-mint в Solana.
gross, fee, net	Десятичные строки. net — то, что попадает на ваш баланс.
applied_fee_percent, customer_fee_percent	Проценты комиссии, зафиксированные для этого депозита при зачислении.
tx_hash, transfer_id, block_height	Подтверждения из блокчейна. transfer_id непрозрачен: сравнивайте его целиком, не разбирайте на части.
source_address	Адрес плательщика, если сеть его раскрывает; иначе отсутствует.
destination_address	Адрес канала, на который пришли деньги.
first_included_block_timestamp	Когда транзакция впервые попала в блок.
explorer_url	Ссылка на обозреватель блоков, если он есть для этой сети.
confirmed_at	Проставляется один раз, при переходе депозита в confirmed.

Поле contract_address объявлено необязательным и пустует только у нативной монеты. Нативных монет среди принимаемых активов нет — значит, в любом депозите, который вы прочитаете, значение есть. То же правило для payment.contract_address описывает GET /v1/invoices/:id: оба ресурса разбирает один и тот же код.

Статусы

Статус	Значение	Финальный
confirming	Обнаружен в цепочке, ждёт нужного числа подтверждений сети	Нет
reorged	Транзакция отменена реорганизацией цепочки	Нет
confirmed	Расчёт завершён, сумма net зачислена на баланс	Да

confirmed необратим: достигнув его, депозит уже не меняет состояние. reorged — состояние покоя, но не финал: если та же транзакция снова попадёт в блок, тот же депозит вернётся в confirming и сможет подтвердиться. Идентификатор pcd_ при этом сохраняется, поэтому второго депозита на один платёж не появляется.

Состояния ошибки нет. Депозит, который был отменён реорганизацией и не вернулся в цепочку, просто остаётся в reorged.

Деньги фиксируются, а не пересчитываются

applied_fee_percent и customer_fee_percent — снимок на момент зачисления депозита. Последующая смена тарифа не меняет уже существующий депозит, и повторное чтение старого депозита возвращает те же gross, fee и net, что и раньше.

Для подтверждённого депозита в рабочей среде эти три суммы считываются из учётной записи, которая зачислила деньги на баланс, — это те же цифры, что и в вашей выписке, а не повторный расчёт. При комиссии 1,0 % депозит на 100 USDT покажет gross 100, fee 1, net 99.

Суммы передаются десятичными строками с обрезанными нулями в конце. Разбирайте их десятичным типом: двоичная плавающая точка теряет точность на масштабе стейблкоинов.

Ошибки

Код	HTTP	Когда
payment_channels_disabled	503	Платёжные каналы не включены для вашего аккаунта в этой среде.
payment_key_required	403	Запрос подписан ключом выплат (rk_).
payment_channel_deposit_not_found	404	Идентификатор не соответствует ничему, доступному этому ключу.
field_invalid_format	400	Сегмент пути не является корректным идентификатором pcd_.

Полный каталог — в Кодах ошибок.