logan

Appearance

1. 获取账户余额和今日收入 ​

接口地址： /merchantapi/wallet/operational/getTotalMoney

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "total_money": "1000.00", // 商户资金账户余额
    "today_income": "50.00", // 今日收益（不含推广收益）
    "promote_income": "10.00" // 今日推广收益
  }
}

2. 获取用户资金 ​

接口地址： /merchantapi/wallet/operational/getUserBalance

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "money": "1000.00", // 可提现余额
    "freeze_money": "500.00", // 用户账户当前冻结余额；待结算页汇总请使用 freezeLog 的 pending_unfreeze_money
    "deposit_money": "200.00" // 运营钱包余额
  }
}

3. 获取充值通道 ​

接口地址： /merchantapi/wallet/operational/getRechargeChannel

  • 2026-2-5 变更：新增字段 u_coin_rate 汇率、min_recharge 最小充值金额、u_channel_id 随机一个存在收款账号的 USDT 充值渠道 ID (使用此固定为类型为 usdt 的支付通道时，响应里的 channels 不需要在使用)

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "fee_rate": 0.05, // 充值手续费率
    "channels": [
      {
        "value": 1, // 支付通道 ID
        "label": "支付宝", // 支付通道名称
        "ico": "https://fast.qqss.net/static/payment/zfb.png" // 支付通道图标
      }
    ],
    "u_coin_rate": 7.2, // 2026-2-5 新增
    "min_recharge": 20, // 2026-2-5 新增
    "u_channel_id": 1 // 2026-2-5 新增
  }
}

4. 运营钱包充值 ​

接口地址： /merchantapi/wallet/operational/doRecharge

请求方式： POST

请求参数：

参数名类型必填说明
amountfloat是充值金额
channelIdint是支付通道 ID

响应示例：

json
{
  "code": 1,
  "msg": "",
  "data": {
    "trade_no": "202312010001", // 充值订单号
    "url": "https://example.com/pay/202312010001", // 支付跳转页面URL
    "order_auto_close_time": 1800, // 订单自动超时关闭时间，单位秒
    "u_coin_rate": 7.2 // 当前USDT汇率
  }
}

支付页面接入说明：

  • 创建充值订单后，前端打开响应中的 url，即 /pay/{trade_no} 收银台页面。
  • 页面可直接跳转、新窗口打开或 iframe 打开；支付页内部会展示二维码、倒计时和“我已支付，点击校验”按钮，并在支付有效期内每 5 秒自动确认一次到账状态。
  • USDT TRC20 支付页通过两个链上数据源交叉查询；到账确认成功后会向父页面和打开方发送 postMessage。status=0 仅表示仍在确认，不代表转账失败。
  • 如果打开支付页时追加 redirect_url 参数，校验成功后会自动跳转到该地址。

redirect_url 用法：

txt
https://example.com/pay/202312010001?redirect_url=https%3A%2F%2Fmerchant.example.com%2Fwallet%2Frecharge%2Fresult

支付成功后会跳转到：

txt
https://merchant.example.com/wallet/recharge/result?trade_no=202312010001&pay_status=success&status=1&msg=支付成功

支付页 postMessage 消息格式：

json
{
  "type": "usdt-trc20-pay-result",
  "trade_no": "202312010001",
  "status": 1,
  "success": true,
  "msg": "支付成功",
  "data": {
    "status": 1
  }
}

前端监听示例：

js
window.addEventListener('message', function (event) {
  var data = event.data;
  if (!data || data.type !== 'usdt-trc20-pay-result') return;

  if (data.success) {
    // 支付校验通过，继续下一步
  }
});

安全备注：

  • 当前 redirect_url 支持跨域跳转，便于多端前端接入。
  • 生产环境如需更严格控制，建议后续增加域名白名单或对 redirect_url 做服务端签名校验，避免开放重定向风险。

4.1 获取新版充值选项 ​

接口地址： /merchantapi/wallet/operational/getRechargeOptions

请求方式： POST

返回商户运营钱包可用的充值方式，以及前端渲染支付页所需的稳定字段。旧的 getRechargeChannel 接口继续保留，新版商户端可以逐步切换到本接口。

返回字段：

字段类型说明
channel_idint充值通道 ID，创建订单时原样提交
method_codestring稳定的支付方式编码，例如 usdt_trc20、alipay、wechat、unionpay
presentationstring支付展示方式：crypto_transfer、scan_qr 或 cashier
namestring支付方式名称
iconstring支付方式图标；优先使用收款接口自定义图标，未设置时返回支付分类默认图标
fee_ratenumber顶层字段，充值手续费率
min_rechargenumber顶层字段，最低充值金额
max_rechargenumber顶层字段，最高充值金额
input_currencystring用户输入金额的币种，当前为 CNY
currencystring该充值方式的实际支付币种
networkstring/null区块链网络，非链上支付为 null
capabilities.manual_verifyboolean是否支持前端手动校验到账
capabilities.exact_amountboolean是否必须严格按服务端生成的金额支付

4.2 创建新版充值订单 ​

接口地址： /merchantapi/wallet/operational/doRechargeV2

请求方式： POST

请求参数：

参数名类型必填说明
amountfloat是充值金额，单位 CNY
channel_idint是getRechargeOptions 返回的通道 ID；兼容旧字段 channelId

创建商户运营钱包充值订单，并直接返回当前通道对应的支付指令。订单类型仍为 deposit_money，不会影响旧接口创建的订单、旧支付页面或现有回调流程。

支付指令字段：

字段类型说明
trade_nostring平台充值订单号
statusint订单状态：0 待支付、1 已支付、2 已关闭
channel.method_codestring稳定的支付方式编码
payment.presentationstring前端展示方式
amount.payment_amountstring服务端最终分配的实际支付金额
amount.payment_currencystring实际支付币种
payment.addressstring/null收款地址，没有时为 null
payment.qr_payloadstring/null二维码内容，可直接生成二维码，没有时为 null
payment.cashier_urlstring旧收银台地址，仅 cashier 模式使用
payment.networkstring区块链网络
remaining_secondsint当前支付指令剩余有效秒数
payment.manual_verifyboolean是否支持手动校验
payment.exact_amountboolean是否必须严格按指定金额支付

USDT-TRC20 订单必须使用 amount.payment_amount。该金额由服务端根据尾数分配并用于区分订单，前端不能自行按汇率重新计算或四舍五入。

4.3 查询新版充值支付详情 ​

接口地址： /merchantapi/wallet/operational/rechargePaymentDetail

请求方式： POST

请求参数：

参数名类型必填说明
trade_nostring是平台充值订单号

重新获取订单状态和支付指令。接口会校验订单所属商户，仅允许当前登录商户查询自己的充值订单。前端刷新支付页或恢复未完成订单时应调用本接口。

兼容说明：

  • 原有 getRechargeChannel、doRecharge 和 /pay/{trade_no} 支付页面保持不变。
  • 新版接口与旧版接口共用充值订单、支付驱动、回调和入账逻辑。
  • 未提供原生二维码或链上转账数据的第三方通道，会返回 presentation = cashier 和 cashier_url，由前端嵌入或打开旧支付页。

5. 获取USDT汇率 ​

接口地址： /merchantapi/wallet/operational/uCoinRate

请求方式： POST

请求参数： 无

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "rate": 7.2
  }
}

6. 充值订单列表 ​

接口地址： /merchantapi/wallet/operational/rechargeOrder

请求方式： POST

请求参数：

参数名类型必填说明
statusint否状态：0=待支付，1=已支付，2=已关闭，3=已退款
date_rangearray否日期范围
channel_idint否支付通道 ID
pageint否页码
limitint否每页数量

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 3,
        "trade_no": "M251119900059", // 充值订单号
        "user_type": 1, // 用户类型：1=商户
        "goods_name": "运营钱包充值 300元", // 商品名称
        "total_price": "315.000", // 订单总价
        "finally_money": "300.000", // 实际到账金额
        "user_id": 1000, // 用户ID
        "status": 1, // 状态：0=待支付，1=已支付，2=已关闭，3=已退款
        "channel_account_id": 1, // 支付通道账号ID
        "channel_id": 1, // 支付通道ID
        "recharge_type": "deposit_money", // 充值类型：deposit_money=运营钱包
        "fee": "15.000", // 手续费
        "create_at": "2025-11-19 15:55:28", // 创建时间
        "pay_at": 1763538936, // 支付时间
        "transaction_id": null // 第三方支付交易号
      }
    ],
    "total": 1
  }
}

7. 订单状态查询 ​

  • 此接口为接口方法，无需登录认证，直接访问即可

  • https://example.com/pay/{订单号} 亦可重新发起支付，支付完成后可能状态为 “订单已支付，请勿重复支付！”，“订单已超时关闭，请重新下单！”，“订单已退款！”

接口地址： /home/pay/orderStatus

请求方式： POST

权限要求： 无需登录认证

请求参数：

参数名类型必填说明
trade_nostring是充值订单号

响应示例：

json
{
  "code": 1,
  "msg": "订单已支付", // 订单已支付
  "data": {
    "status": 1 // 订单状态：1=已支付
  }
}
json
{
  "code": 0,
  "msg": "订单不存在",
  "data": "error"
}
json
{
  "code": 0,
  "msg": "订单超时已关闭",
  "data": {
    "status": 2 // 订单状态：2=已关闭
  }
}
json
{
  "code": 0,
  "msg": "订单已退款",
  "data": {
    "status": 3 // 订单状态：3=已退款
  }
}