1. 接入概览

1. 向熠能获取 appId / appSecret（此时不可交易）
2. 走标准进件：上传图 → 入驻 → 业务开通 → 实名
3. progress.ready=true 后统一下单
4. 接收异步通知；必要时查单 / 退款

演示商户：yn_demo_merchant / demo_secret_change_me。Swagger：/doc.html

2. 签名鉴权

所有 /v1/** 请求必须带：

待签名字符串

复制{appId}
{timestamp}
{nonce}
{METHOD}
{path}
{sha256Hex(body)}

Sign = hex(hmac_sha256(appSecret, 上述字符串))。GET 无 body 时对空字节做 SHA256。path 示例：/v1/payments/create。

3. 接口清单

4. 标准进件（必走）

所有新商户必须走标准进件。先拿凭证，再按序调用：

上传影像

复制POST /v1/onboard/files
{ "fileType":"F01", "fileName":"license.jpg", "fileBase64":"..." }

企业入驻

复制POST /v1/onboard/enterprise
{
  "requestNo": "REG001",
  "payload": { "reg_name":"某某科技", "license_code":"...", "card_info":{} }
}

个人入驻用 /v1/onboard/individual。详细字段透传斗拱官方文档。GET /v1/onboard/progress 查看是否 ready。

5. 统一下单

复制POST /v1/payments/create
{
  "outTradeNo": "M202607260001",
  "amount": 0.01,
  "subject": "测试商品",
  "channel": "WECHAT_APP",
  "clientIp": "1.2.3.4",
  "notifyUrl": "https://merchant.example.com/yineng/pay-notify",
  "extra": { "openid": "oXXXX" }
}

同步成功只表示受理；支付终态以异步通知为准。

6. 查单 / 关单

GET /v1/payments/{outTradeNo} — 未终态会同步通道。

POST /v1/payments/{outTradeNo}/close — 仅微信/支付宝；已支付不可关。

7. 退款

复制POST /v1/refunds
{
  "outTradeNo": "M202607260001",
  "outRefundNo": "R202607260001",
  "amount": 0.01,
  "reason": "用户取消"
}

查询：GET /v1/refunds/{outRefundNo}

8. 异步通知（熠能 → 商户）

向你的 notifyUrl POST JSON，Header 同请求签名规则；验签 path 固定 /pay/notify，密钥用 notifySecret。

复制{
  "outTradeNo": "M202607260001",
  "tradeNo": "YN...",
  "status": "SUCCESS",
  "amount": 0.01,
  "channel": "WECHAT_APP",
  "hfSeqId": "..."
}

务必：验签、幂等、快速返回 2xx；丢失时用查单兜底。

9. 错误码

本地 mock 模拟成功：POST /internal/mock/payments/{outTradeNo}/success