帮助中心
运营问题
术语定义
| 术语 | 定义 | 说明 |
|---|---|---|
| Partner（PID） | 合作伙伴 / 渠道商 | 与 Paydify 建立合作关系的实体，可发展下游商户 |
| Merchant（MID） | 商户 | 直接使用 Paydify 支付服务的商业实体 |
| x-api-key | 应用 Id | 承载支付应用和子商户功能的唯一标识 |
| x-api-secret | 密钥 | |
| Payin | 收款 | 用户向商户支付稳定币的业务流程 |
| Payout | 付款 | 商户向用户 / 供应商支付稳定币的业务流程 |
| Custodian | 资金托管 | 收 U 入金后，由 Paydify 托管余额，再用于批量付 U 或法币结算 |
| CKP | Checkout Page | Paydify 托管的中间收银台页面 |
收款
收银台（CKP）、Deeplink、QRCode 分别适合什么场景？
| 集成方式 | 适用终端 | 用户路径 |
|---|---|---|
| CKP | WAP / App | 商户跳转 Paydify 收银台，由收银台拉起钱包 |
| Deeplink | WAP / App | 商户自渲染下单页，直接跳指定钱包 |
| QRCode | Web (PC) | PC 渲染二维码，用户手机扫码支付 |
三者使用同一个 POST /payin/v1/createPayment 接口，只是消费 data.httplink / data.deeplink / data.qrCode 三个字段中的不同字段。
支付状态 state 取值有哪些？
| state | 含义 | 是否终态 |
|---|---|---|
INIT | 订单已创建，尚未感知到链上支付 | 否 |
PAYING | 已感知到链上发起，等待区块确认 | 否 |
PAID | 支付完成，资金已确认到账 | 是 |
FAILED | 支付失败（链上失败 / 金额不匹配 / 用户取消） | 是 |
TIMEOUT | 订单超时未支付（达到 lifetime） | 是 |
为什么订单要做「Webhook + 主动查询」双保险？
- Webhook（主路径）：Paydify 在订单状态变更时主动推送，延迟最低；
- 主动查询（兜底路径）：用于商户回调端临时不可用、网络抖动等场景，通过
POST /payin/v1/getPaymentStatus拉取真实状态。
只接 Webhook 不接查询，遇到回调送达失败时会丢单；只接查询不接 Webhook，会有较大延迟和无谓轮询成本。
充值
入金地址会变吗？
不会。每个（App + 链）下的充值地址是 永久固定 的，KYC 通过后即生成。商户可以放心把它写入自己的财务系统。
没配充值白名单的入金会怎样？
资金先进入 FROZEN（冻结），由商户在 Portal 上人工「解除冻结入账」或「原路退回」。已配白名单时，匹配通过的入金自动归集到余额。
提现
Crypto Withdraw 余额不足会怎样？
接口直接同步返回 INSUFFICIENT_BALANCE，不进入异步流程，余额不会被扣减。商户可以补足余额后用相同 mchWithdrawId 重试。
Fiat Withdraw 报价单的有效期是多久？
默认 60 秒。超过后需重新调用 POST /payout/v1/fiat-withdraw/quote 取新报价。
Fiat Withdraw 失败资金会回到哪里？
回流商户的 Paydify 平台账户余额；如果是收款人信息错误导致的清算失败，会扣除 fail fee 后再回流。
付款
单笔与批量 Payout 有什么区别？
单笔 Payout 适用于向单个收款人付款；批量 Payout 支持在商户 Portal 或通过 API 一次提交多笔付款，适合主播发薪、地推佣金等场景。详见 Payout 概述。
Deposit 白名单与 KYA 扫描如何影响付款？
未在白名单内的入金地址会被冻结；发起 Payout 前，收款地址会经过 KYA 安全扫描，高风险地址可能被拦截。详见 Payout 概述 与 数据字典。
退款
退款由谁发起？
当前仅支持商户通过 createRefund API 发起退款，没有其他渠道。
退款分哪些场景？
| 场景 | 资金路径 | Paydify 退款流程 |
|---|---|---|
| CEX 退款（Binance / Bitget / OKX 等） | 原路收 → 原路退 | 调 createRefund，Paydify 负责退款上链，支持多次部分退款；ServiceFee 按照退款金额百分比退还 |
| DEX 退款（MetaMask / Bitget Wallet / OKX Wallet 等） | 用户 → 商户地址（点对点） | 由于交易资金是点对点直接结算至商户地址，退款需要商户线下转账完成，并调用 createRefund 更新订单状态；或通过平台 Payout 能力完成退款 |
退款金额怎么算？
退款金额校验逻辑：SUM(已退金额) + 本次退款金额 <= 原单金额。
- 稳定币订单：用户接收退款金额 = 商户申请退款金额。 例：订单 100 USDT，用户实付 100 USDT，申请退 20 USDT → 用户收到 20 USDT；
- 法币订单：用户接收退款金额 = 商户申请法币退款金额 / 法币订单总金额 × 用户已支付稳定币金额。 例：订单 100 USD，按照下单时汇率，用户实付 101 USDT，申请退 20 USD → 用户收到 20 USD / 100 USD × 101 USDT = 20.2 USDT。
哪些费用不退？
- 已执行的 KYT / KYA 链上地址扫描费用 不退；
- 用户通过 DEX 交易产生的 链上 Gas 费 不退；
- 其余 ServiceFee 按「退款金额占总订单金额」百分比同比退还。
对接问题
异步回调验签里 apiPath 是什么？
填您接收异步回调的接口 path，和平台发起回调时请求的 path 保持一致，不包含域名。
例：回调地址是 https://xxx.com/api/payment/notify，则 apiPath 填 /api/payment/notify。
回调成功后应答什么内容？
返回 HTTP 200 + 响应体 success（裸字符串，建议 Content-Type: text/plain）。Paydify 收到此应答才认为通知送达，否则按 1m / 5m / 30m / 2h / 6h / 12h / 24h 间隔最多重试 7 次。详见 回调通知。
同一个 txnId 的回调可能被推送几次？
可能 ≥ 1 次。Paydify 在网络抖动、商户回调端临时不可用、用户链上多次事件等情况下都会推送通知，商户侧需要按 txnId + state 做幂等去重。
我的服务器时钟和 Paydify 不一致，会怎样？
签名校验会带时间戳，时钟偏差过大的请求会被认为「过期」而被拒收。请同步 NTP，保持服务器时钟准确。回调端也需要同步时钟。
Sandbox 与 Live 凭据可以混用吗？
不可以。沙箱与生产的 x-api-key / x-api-secret 相互独立，沙箱凭据只能调沙箱域名，生产凭据只能调生产域名。详见 服务域名。