无需 KYC · 客户付法币，商家收稳定币 · 入驻开放申请中立即申请 →

文档中心 / 支付状态详解

支付状态详解：OPEN、PARTIALLY_FILLED、FILLED、OVER_FILLED 与 CANCELLED

一笔支付从创建到结束，会经过几种状态。弄清楚每种状态的含义，才知道什么时候发货、什么时候退款。

先看结论：PayRam 的支付只有五个状态。FILLED 表示付满了，可以发货；PARTIALLY_FILLED 是少付，先别发货；OVER_FILLED 是多付，发货并决定怎么处理多出来的部分；OPEN 还在等付款；CANCELLED 是已取消或已过期。

本页内容
  1. 五个状态一览
  2. 状态是怎么流转的
  3. 确认进度：付款到账前的中间状态
  4. 每种状态怎么处理
  5. 减少少付和多付的几个办法
  6. 用 Webhook 和状态接口对准订单状态
  7. 常见问题

1. 五个状态一览

状态含义你该怎么做
OPEN支付已创建，还没检测到付款（或已收金额为零）继续等待，订单保持“待付款”
PARTIALLY_FILLED检测到付款，但已收金额少于请求金额不要发货。让客户补足，或按你的规则处理，见下文
FILLED已收金额等于请求金额按正常流程发货或开通服务
OVER_FILLED已收金额多于请求金额可以发货，同时决定怎么处理多收的部分
CANCELLED支付已取消，通常是支付链接过期了关闭订单，需要的话让客户重新发起

在后台的支付链接列表里，你会看到更简化的显示：待处理（Pending）、成功（Successful）、已取消（Cancelled）。接口和 Webhook 里是上面这五个值。

2. 状态是怎么流转的

OPEN  →  （检测到付款 → 确认中：1/N、2/N … N/N）  →  FILLED
                                                 或 PARTIALLY_FILLED
                                                 或 OVER_FILLED
OPEN  →  CANCELLED（支付链接过期或被取消）

支付链接默认 24 小时后过期，过期后状态变为 CANCELLED。你可以在创建支付时用 expire 指定别的时间。

3. 确认进度：付款到账前的中间状态

链上付款不是瞬间完成的，需要等区块确认。在这期间，Webhook 会带着两个数字：confirmation_current（已有的确认数）和 confirmation_required（需要的确认数），例如 3 / 12、5 / 12。你可以用它在页面上显示“确认中 5 / 12”，让客户知道没有卡住。

在最终的已关闭或已取消通知里，这两个数字都是 0。所需确认数达到之前，支付不会被判定为付满。

4. 每种状态怎么处理

下面是我们的建议做法，具体规则请按你自己的业务政策来定。

FILLED：付满了

这是发货的信号。收到通知后，先校验签名并按 reference_id 做幂等，再把订单改成“已付款”。关键订单可以再用状态接口复核一次，见 Webhook 完全指南。

PARTIALLY_FILLED：少付

官方说明少付时，支付会一直保持未完成，直到收到全额。常见做法：

  • 通知客户还差多少，请他在支付链接过期前补足。
  • 到期仍未补足，由你决定：关闭订单并把已收到的部分退还，或者与客户协商补差价。
  • 退款是一笔新的出款，从热钱包发出，见 退款与出款。

OVER_FILLED：多付

多出来的金额会清楚地显示在后台，由你决定：把多收的部分退还给客户，或者记为客户余额，抵扣以后的账单。无论选哪种，都要保留记录，并在订单备注里写清楚。

CANCELLED：已取消或过期

关闭订单即可。客户想继续买，就重新创建一笔支付，不要复用已过期的链接。如果遇到客户在过期之后才付款的情况，先在后台查看这笔款项的记录，再决定退款或补订单，不要凭印象处理。

5. 减少少付和多付的几个办法

  • 提醒客户从交易所提币时留意手续费。有些交易所会从提币金额里扣除网络手续费，客户实际到账会少于应付金额。让客户在提币时选择“手续费另算”，或者多提一点。
  • 限定币种和网络。创建支付时用 currency 和 network 把选择缩小，比如只收 Base 上的 USDC，客户选错网络的机会就少了。
  • 在付款页上写清楚金额和网络。转错网络或转错币种，资金可能无法找回。
  • 用稳定币付款。用 USDT、USDC 付款时，应付金额几乎不受币价波动影响，客户不容易因为价格变动而少付。

6. 用 Webhook 和状态接口对准订单状态

推荐两种方式一起用：

  1. Webhook：状态一变就通知你，是主要来源。
  2. 状态接口：用保存的 reference_id 主动查询，返回里的 paymentState 就是当前状态。用来复核和兜底。
curl --location 'https://pay.payramhost.com/api/v1/payment/reference/<reference_id>' \
  --header 'API-Key: <your_api_key>'

完整的对接流程见 API 对接教程。

7. 常见问题

PARTIALLY_FILLED 之后客户补了钱，状态会变吗？

会。官方说明少付时支付保持未完成，直到收到全额；累计达到请求金额后，状态变为 FILLED，通常会收到新的通知。所以处理逻辑不能写成“收到一次就结束”，要按状态变化逐次更新。

状态会倒退吗，比如从 FILLED 变回 OPEN？

正常流程里状态是单向推进的。但为了保险，你的处理逻辑应该只接受“更靠后”的状态，忽略过时的重复通知。

收到的通知里 status 是 OPEN，是不是出问题了？

不是。OPEN 表示支付已创建、还没有检测到付款，继续等待即可。付款被检测到之后，通知里会带上确认进度，见上文。

CANCELLED 之后还能再付款吗？

不要这样做。已取消的支付应当当作结束。让客户重新发起一笔新的支付。

  • Webhook 完全指南：PayRam Webhook 怎么接：在后台添加回调地址，用 X-Payram-Signature 校验签名，理解重试规则与支付状态，做幂等处理，附 Node.js 和 Python 示例。
  • API 创建支付：用 PayRam API 给自己的网站接加密货币收款：创建支付拿到付款链接，把客户引到支付页，用 Webhook 和状态接口确认到账，并用订单号对账。附 curl、Node.js、Python 示例。
  • 退款与出款：链上支付没有拒付，退款要商家手动发起。本文讲 PayRam 出款（Payouts）的流程：地址簿、审批与验证码、限额设置、状态含义，以及退款前该核对什么。