获取

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 约定的数字链 ID（如以太坊主网为 1，Tron 为 728126428）
payment.contract_address	string?	代币的链上标识——EVM 和 Tron 上为合约地址，TON 上为 jetton master，Solana 上为 SPL mint。schema 里可为空，因为原生币没有这个标识；而接受的资产里没有原生币，所以真实账单上这个字段始终有值。GET /v1/payment-channel-deposits/:id 对它自己的 contract_address 给出同一条规则
payment.expected	string	客户应付的加密货币金额
payment.address	string?	客户付款的充值地址。账单处于 awaiting_client 时整个 payment 对象不出现在响应中，因此该字段在处理中的账单上不会显示为 null——此时根本没有 payment 可读
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?	每笔转账的详情——至少检测到一笔链上转账后出现。见下文

Transfer 字段

payment.transfers[] 中每一项：

字段	类型	说明
tx_hash	string	链上交易哈希（格式随网络而定）
amount	string	转账的加密货币金额
status	string	confirming（等待确认数）或 confirmed
created_at	unix timestamp	我们的管线在已处理区块中首次观测到该转账的时间。这是我们服务器的墙钟时间，不是链上区块时间戳——管线有延迟时两者不同。下面"剩余秒数"公式用这个字段（不是账单顶层的 created_at）
confirmed_at	unix timestamp?	转账达到所需确认数的时间。仍待确认时为 null
required_confirmations	integer?	按该转账美元金额档位达到 confirmed 所需的确认数。凡是按链自身 finalized 承诺结算、而不数区块的网络，这里都是 null——今天是 BNB Smart Chain、Polygon、Solana、Avalanche 和 Plasma。请按 null 分支，不要按网络清单分支：哪些链走最终性属于运营参数，可能变化
estimated_confirmation_at	unix timestamp?	转账预计结清的时间。数区块的网络上，观测时按 transfer.created_at + required_confirmations × network_block_time 计算；最终性网络没有区块数可数，取 transfer.created_at 加上该链常见的最终性耗时，等待条照样画得出来。静态值——不会在请求之间变动，每次轮询都相同，直到转账确认（或其美元档位变化）。客户端计算"剩余秒数"：max(0, estimated_confirmation_at − now)
explorer_url	string?	该交易在网络区块浏览器中的直接链接（Tronscan / Etherscan / Tonviewer 等）。网络未配置公开浏览器时为 null。可原样渲染为可点击链接——无需任何转换

账单状态

每个账单都带一个 status 字符串。同一个值同时驱动商户 API 响应、收银台 SSE 流和 webhook 负载——只有一个事实来源。下表是逐状态参考：该值何时出现、是否终态、背后的精确条件。状态流转图和两种创建流程见 付款流程。

终态（terminal）状态是最终的：账单停在那里，不再变动。五个终态——paid、paid_over、underpaid、expired、cancelled。

状态	终态	适用场景
awaiting_client	否	每个账单的初始状态。尚未选定代币和网络，因此还没有充值地址。只允许在此状态取消
awaiting_payment	否	代币、网络和充值地址已锁定。Paymos 正在监听该地址的入账转账
confirming	否	转账已上链，正在累积其金额档位所需的确认数
underpaid_waiting	否	已清算金额不足应付金额，账单保持打开等待补足。仅当 allow_multiple_payments 为 true 时才会进入此状态
paid	是	应付金额已全额清算（或在项目的少付容忍范围内）
paid_over	是	清算金额超过应付金额；整笔转账全额入账
underpaid	是	账单以不足额关闭——要么过期时低于应付金额，要么 allow_multiple_payments 为 false 时单笔付款不足
expired	是	计时耗尽且未收到任何款项，或法币流程中选币窗口在选择代币前已失效
cancelled	是	商户在账单仍处于 awaiting_client 时取消了它

错误

完整目录见 错误码。每个错误响应中的 type URI 直接链接到对应条目。