QRCode 扫码集成

适用于 PC 端下单场景：商户在 PC 下单页渲染 createPayment 返回的 qrCode 为二维码，用户使用手机钱包扫码 / 手机相机扫码后，自动跳转到指定钱包完成支付。

维度	说明
用户体验	佳
集成工作量	较低（渲染 base64 图片即可）
支持的平台	Web（PC）

交互示意

此场景适合 PC 页面，在商家的下单页面渲染出通过 Paydify 下单返回的 qrCode 为二维码，消费者使用手机相机/浏览器扫码后，自动跳转到指定钱包完成支付。

与 CKP / Deeplink 的差异

三种模式共用同一个 POST /payin/v1/createPayment 接口，仅在客户端如何引导用户上不同：

阶段	CKP	Deeplink	QRCode
客户端介质	浏览器跳转 `httplink`	浏览器跳转 `deeplink`	浏览器渲染 `qrCode` 二维码
适用终端	手机 WAP / App	手机 WAP / App	PC Web
用户操作	点击按钮跳转	选择钱包后跳转	使用手机扫码

完整步骤 0 / 1 / 3 / 4 / 5 复用 CKP 集成指南，本页只列出 QRCode 独有的步骤 1 字段约束与步骤 2 二维码渲染方式。

集成准备

完成 KYC 并拿到 x-api-key / x-api-secret（商户 Portal - 开发者中心获取）；
已下载并接入服务端 SDK；
PC 下单页能渲染 base64 图片即可。

集成步骤

集成时序

步骤 1：创建订单（指定钱包 + 链）

调用 POST /payin/v1/createPayment。QRCode 模式下，必须指定钱包与链，让 Paydify 生成对应钱包的扫码 payload：

字段名	必传	描述
`payMethod1`	是（QRCode 模式必传）	支付使用的钱包，枚举值见支持的链和币种
`payMethod2`	是（QRCode 模式必传）	支付使用的链
其他字段	—	与 CKP 完全一致，详见 CKP 集成 - 步骤 1

请求示例：

{
  "mchTxnId": "MCH_TXN_20260610_002",
  "txnAmount": "0.01",
  "currency": "USDT",
  "checkoutMode": "MERCHANT",
  "payMethod1": "BINANCE",
  "payMethod2": "BNB",
  "notificationUrl": "https://your-domain.com/api/payment/notify",
  "successReturnUrl": "https://your-domain.com/pay/success",
  "failReturnUrl": "https://your-domain.com/pay/fail",
  "pendingReturnUrl": "https://your-domain.com/pay/pending",
  "txnTitle": "Test Payment Order",
  "source": "web",
  "txnDesc": "Payment for test product",
  "accountInfo": [
    {
      "toAddress": "0x1111111111222222222233333333334444444444",
      "network": "ETH"
    }
  ],
  "payerInfo": {
    "uid": "USER_123456"
  },
  "mchExtInfo": "{\"orderId\":\"ORD_2025081201\",\"productId\":\"PROD_001\"}"
}

响应示例：

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "txnId": "P5118170010653393152",
    "mchTxnId": "MCH_TXN_20260610_002",
    "httplink": "https://app.binance.com/payment/secpay?linkToken=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&_dp=Ym5jOi8vYXBwLmJpbmFuY2UuY29tL3BheW1lbnQvc2VjcGF5P3RlbXBUb2tlbj14eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eCZyZXR1cm5MaW5rPWh0dHBzOi8veW91ci1kb21haW4uY29tL3BheS9zdWNjZXNz",
    "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&returnLink=https://your-domain.com/pay/success",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAACjklEQVR4Xu2YzW6lMAxGzYrHyJsS8qY8wiyzwvMdJ9y2TKV2OdfCQijYJ5Xy+QduzX9jf+zu+dYe7GYPdrMHu9l/jx0mW711W9z39Vh62a14LycBq4kwLc7VXVgvzb1p43psXDOaBtvM5CQUCsikjEuQcCbEuOtRgvgZ67TY+uKpcKcesmE1PFWh6Ggx+0pff9cL742ZDOc/FwFLhA3TwQ+pscuPLOytVywLFgdf6eLWyzm62DSrpz8RNl64h0WukaUb5S3nqPk8mJKOCEGqi7WmAJau7i76CzUPRsYdki0SQXl38k72l1QYGcfJt6KcswY2KQOJZcF49JClxfEJdXkOi72ZMK3POD4PRO0qgOlMgzkzqkRHU+oKnUih7B81mj0LduhxWwGcjyhVOBk/Leb2hyApMKNtW1T4eJQ4tobny+B6d4yQKe8xuC5lUKOGPpmwUANNpAMKdODdYhdDOw82BKm8ZGfSnYwjhffiibCd/tXskg6EUGZKwcZEGKEzPhQNfmrSKIZDNZAJ06lbFLYPJgZX7UxpQ5Y8GJ4ZVd7j5RsTrMUiEUbSCTGcyXVES1z4PQ92ZZl0j/nMHFtYA6fCuNS/zC4wQlH5aufPFfL+mJF0Lvyv1K9sFOOJsC3yu+uuXCvpHjUwXlK5sBofGIJ3ajukcP4bIzvjngbbwo/TsIpHe+MxFmmw2okqxD1eQzuzmkeLqsiCDTvQYWSfqcWuihPLgsXBP2aX5lXZpzKEaiKs0rbylJMN2OKvXz1E02Dj7GTcsXZ5Jp8OU4W3OaxwVn1vhBr5sOX15g1ybvk03xJg1WnksNBBJK2tNXOsJsI498p94/hUOxLh/VLk74/9bA92swe72YPdLAP2F7nrsbaKyGNyAAAAAElFTkSuQmCC",
    "state": "INIT",
    "errorMsg": ""
  },
  "success": true
}

QRCode 模式下，您主要使用 data.qrCode 字段。

步骤 2：在下单页渲染二维码

data.qrCode 是 data:image/png;base64,... 格式的 Data URL，可直接作为 <img> 标签 src 渲染：

<div class="checkout-qrcode">
  <p>请使用 Binance App 扫描下方二维码完成支付</p>
  <img src="{{qrCode}}" alt="Paydify payment QR" width="240" height="240" />
  <p>订单号: {{mchTxnId}}</p>
</div>

实时刷新支付状态

二维码渲染后，下单页需要轮询订单状态，给用户即时反馈：

const pollPaymentStatus = async (txnId) => {
  while (true) {
    const { data } = await fetch('/your-backend/getPaymentStatus', {
      method: 'POST',
      body: JSON.stringify({ txnId })
    }).then(r => r.json());

    if (['PAID', 'FAILED', 'TIMEOUT'].includes(data.state)) {
      // 跳转到对应结果页
      return data.state;
    }

    await new Promise(r => setTimeout(r, 3000)); // 每 3 秒轮询一次
  }
};

关键约束：

轮询频率建议 3–5 秒一次，避免接口压力过大；
同时保持 Webhook 通道作为主路径——轮询只是为了刷新前端 UI，订单状态最终以 Webhook 为准（参见步骤 3 双保险）；
二维码自带过期时间（默认 30 分钟，由 lifetime 控制）。建议在前端显示一个倒计时，超时后提示用户刷新订单或重新下单；
对账时建议引导用户扫码后不要关闭下单页，方便订单到达终态后立即展示结果。

复用 CKP 的部分

步骤 0：加 / 验签 —— 完全一致，参考 CKP 集成 - 步骤 0；
步骤 3：获取支付结果 —— Webhook + 主动查询双保险完全一致，参考 CKP 集成 - 步骤 3 与回调通知；
步骤 4：发起退款 —— 完全一致，参考发起退款；
步骤 5：获取对账单 —— 完全一致，参考获取结算文件。

上线检查清单（额外项）

[ ] 二维码在常用分辨率（PC / 笔记本）下扫描成功率正常
[ ] 已在二维码旁边显示倒计时与订单号
[ ] 已实现 3–5 秒轮询 getPaymentStatus，并在终态时立即跳转结果页
[ ] Webhook 与轮询双保险都已联通，订单状态最终以 Webhook 为准
[ ] 至少使用 1 个主流钱包真机扫码沙箱通过