← 全部接入指南接入指南 · API / PHP 示例通过 MochiPay API 接入加密货币支付
从应用创建和查询支付订单。PHP Demo 1.1.1 支持 PHP 7.0–8.4，提供 order.php、callback.php、含两种展示模式的 checkout.php、本地弹窗资源和英文 README。站内（默认）或 HPP 均使用同一支付订单。
演示流程 · 示例配置 · 请用小额真实付款验证自己的设置。
付款流程示意图，站内支付与 HPP 使用同一笔订单，最终状态由服务器验证。查看完整付款结果
此演示使用示例数据。请在自己的环境中用小额真实付款验证这些结果；实际支付金额和确认要求由订单决定。
01 · 准备 MochiPay 账户
- 创建账户 及 启用订阅.
- 打开 钱包，选择添加 HD 钱包 → 生成新钱包，私下备份助记词并保存，启用测试使用的资产 / 网络。
- 在此处设置客户能识别的显示名称 账户资料.
- 打开 API 凭证 并复制 API Key 和已保存的 API Secret。首次设置若未保存密钥，请重新生成并妥善保存。重新生成现有密钥会使使用旧密钥的接入失效。
完成标准： 你的订阅与收款钱包均有效，并已取得下方所需凭证。
查看图文账户设置 →选择站内支付或 HPP
| 模式 | 客户体验 | 服务器责任 |
|---|
| 站内支付（默认） | 在你自己的域名展示付款对话框，包含精确数量、地址、网络、二维码及状态。 | 创建并保存付款绑定，通过自己的后端查询，只返回安全的付款展示信息。 |
|---|
| HPP | 跳转到返回的 MochiPay payment_url。 | 保存相同订单绑定，并通过服务器间通信验证回调 / 返回。 |
|---|
结账模式是接入端的偏好设置，并非 API 字段。两种链接使用同一订单，切换模式时不要创建新订单。经典 SaaS 仅支持 HPP。
支持全部五种方式：USDT_TRC20、USDC_ERC20、BTC_BITCOIN、ETH_ERC20 和 SOL_SOLANA。唯一金额方向默认为 UP，也支持 DOWN。每种提供的方式都需启用对应收款钱包。
03 · 下单并支付测试订单
打开 order.php，用唯一商户订单编号及已配置支付方式创建小额演示订单。选择 ON_SITE 或 HPP，打开创建结果的对应链接。结果也提供嵌入商城结账和 PHP HPP 跳转链接，两者由 checkout.php 实现并使用同一订单。
- 匹配所选资产/网络。测试 USDT_TRC20 时，付款钱包需有 USDT 和足够支付网络手续费的 TRX。其他方式需使用对应网络及适用的手续费资产。
- 发送 付款页上的精确金额 发送至显示的收款地址，不能取整或复用其他订单地址。
- 等待所需链上确认，并等 MochiPay 订单状态变为
PAID.
商城/API 示例可用美元标价。MochiPay 在创建订单时锁定汇率，唯一金额调整可能改变最终应付金额。请以收银台显示金额付款。
成功检查： MochiPay 订单显示 PAID 且已记录交易，仅打开浏览器返回页不构成付款证明。
04 · 验证结果与钱包收款
从应用按系统 order_id 查询订单。仅当验证查询返回 PAID，且匹配已保存系统 ID、商户编号、原始金额/币种、所选资产/网络、收款地址、准确应付及预期实收金额时接受付款。以原子且幂等的本地事务履约。callback.php 使用私有演示记录示范通知及浏览器返回验证，不执行履约；请以生产数据库和履约事务替换临时记录及回调 TODO。阅读附带 README。
核对付款交易、收款地址与 MochiPay 订单，查看收款钱包或区块链浏览器。资金已在您的收款钱包中，无需申请平台提现。
转移资金需使用兼容的钱包，并考虑区块链确认及原生网络手续费。 阅读收款钱包管理指南 →
钱包恢复与精确金额
创建订单前持久保存尝试记录。超时后先查询同一唯一商户编号，不要盲目再次创建。获知 order_id 后用其查询。PHP 或 JavaScript 转浮点前将十进制响应值保留为字符串，准确显示 pay_amount。附带二维码仅编码地址，顾客需输入显示金额。
开发自己的 API 客户端时
使用 X-Mochi-Key 及 X-Mochi-Signature。创建订单对准确的 JSON 正文做 HMAC-SHA256 签名，并使用 Base64 编码。查询订单对去掉开头问号的准确查询字符串签名。签名密钥必须保存在服务端。
测试未完成时
无法创建支付选项或订单
检查订阅状态、已启用收款钱包、支付方式代码、凭据及订单币种汇率对。插件还需确认测试使用的商城范围及顾客已启用该支付方式。
付款仍在等待中或金额不足
核对交易的资产、网络、地址和准确应付金额，并等待所需确认数。请勿仅凭截图或浏览器返回将商城订单标记为已付款。
MochiPay 已付款，但商城 / 应用状态未更新
确认通知/回调端点能通过 HTTPS 公开访问，且未被身份验证或防火墙拦截。确认接入能查询 MochiPay 并检查错误日志。仅收款链接更新 MochiPay，不会更新外部商城。
可选的开单重试去重
原有接入无需传入 request_id 即可继续使用。若要在超时后复用同一支付订单，可先将可选 request_id 加入 JSON 正文，再按原方式计算 HMAC 签名。
{"merchant_order_id":"STORE-1001","amount":25,"currency":"USD","payment_method":"USDT_TRC20","request_id":"STORE-1001:create:v1"}
使用 1 至 64 个 ASCII 字母、数字、点、下划线、冒号或连字符。请求号绑定一个商户及一个请求内容。重试时复用相同请求号和内容，原响应字段保持不变，并返回原订单的当前状态。请求号不会自动到期；需要新的付款尝试时，请使用新的请求号。
HTTP 409 REQUEST_IN_PROGRESS：按 Retry-After 指示稍后重试相同请求。HTTP 409 REQUEST_ID_CONFLICT：相同请求号传入了不同内容。不要为了绕过超时而生成新请求号。ON_SITE 和 HPP 都可继续使用返回的支付字段或 payment_url。