更新记录

1.0.1（2026-04-18）

• 完善支付流程

1.0.0（2026-04-16）

初始化版本

平台兼容性

云端兼容性

uni-app(5.0)

云函数类插件通用教程

使用云函数类插件的前提是：使用HBuilderX 2.9+

tian-third-payment 第三方支付插件

面向 uni-app + uniCloud 项目的第三方支付插件，提供从实名认证到绑卡、支付、退款、提现、回调处理的一体化能力。

适用于希望在项目中快速接入多支付渠道、并具备后台管理与问题补偿能力的开发者。

功能总览

• 实名认证
  • 复用 uni-id-users.realname_auth 作为统一实名资料
  • 支持身份证 OCR 与人脸核验流程接入
• 入网管理
  • 按渠道独立维护入网状态
  • 支持人工触发查询补偿
• 银行卡管理
  • 绑卡、重发验证码、确认绑卡、解绑、查询
• 支付能力
  • 统一支付下单、确认、查询、取消
  • 支持支付回调解析与状态落库
• 退款能力
  • 发起退款与退款状态查询
• 提现能力
  • 提现申请、提现查询、提现回调处理
• 后台管理能力
  • 渠道配置、提现审核、回调日志查看、人工查询补偿

支付渠道

说明：预留扩展表示已预置渠道标识和对接骨架，具体生产接口需按对应渠道文档完成二次实现。

目录结构

插件目录：uni_modules/tian-third-payment

建议重点关注：

• pages/：前端页面
• common/js/：插件请求与公共方法
• uniCloud/cloudfunctions/tian-third-payment/：云函数逻辑
• uniCloud/database/：数据表结构

环境要求

• HBuilderX（建议使用最新稳定版）
• uni-app + uniCloud 项目
• 已启用 uni-id（用于用户体系与实名资料存储）
• 已安装并可使用 uni-config-center

安装步骤

1. 安装插件

将插件导入项目后，确认目录存在：uni_modules/tian-third-payment。

2. 导入数据表

按插件内数据库文件导入以下核心表（以实际 uniCloud/database 文件为准）：

• tian-third-payment-channels
• tian-third-banks
• tian-third-payment-banks
• tian-third-onboardings
• tian-third-user-banks
• tian-third-recharges
• tian-third-withdrawals
• tian-third-callback-logs
• tian-third-cache

如果你需要实名地址三级联动，请同时导入：

• opendb-city-china

3. 上传云函数

上传插件相关云函数及公共模块到 uniCloud。

4. 导入页面路由

将插件提供的 pages_init.json 中页面配置合并到项目 pages.json。

5. 配置 uni-config-center

在 uniCloud/cloudfunctions/common/uni-config-center/tian-third-payment/config.json 中配置支付参数。

示例：

{
  "app": {
    "payment": {
      "alipay": {
        "uniPay": "initAlipay",
        "name": "支付宝",
        "payName": "支付宝支付",
        "appId": "your-app-id",
        "mchId": "your-mch-id",
        "privateKey": "your-private-key",
        "alipayPublicKey": "your-alipay-public-key"
      },
      "wxpay": {
        "uniPay": "initWeixin",
        "name": "微信",
        "payName": "微信支付",
        "appId": "your-app-id",
        "mchId": "your-mch-id",
        "key": "your-api-key",
        "pfx": "your-cert.p12"
      }
    }
  },
  "third-payment": {
    "payeasenet": {
      "merchant_id": "your-merchant-id",
      "partner_id": "",
      "pay_name": "首信易支付",
      "gateway": "",
      "private_pfx": "client.pfx",
      "private_pfx_password": "your-pfx-password",
      "private_key": "",
      "platform_certificate": "platform_publickey.cer",
      "sftp_host": "merchant-sftp.5upay.com",
      "sftp_port": 2822,
      "sftp_username": "your-merchant-id",
      "sftp_private_key": "your_sftp_key.rsa",
      "sftp_private_key_passphrase": "",
      "sftp_remote_dir": "/serviceprovider"
    }
  }
}

6. 上传证书与密钥文件

将证书文件上传到：

uniCloud/cloudfunctions/common/uni-config-center/tian-third-payment

常见文件包括：

• client.pfx
• platform_publickey.cer
• *.rsa（如需 SFTP 上传资质文件）

关键流程说明

实名认证流程

1. 上传身份证正反面
2. OCR 识别并回填姓名/身份证号/证件有效期
3. 调用 uni.startFacialRecognitionVerify
4. 写入 uni-id-users.realname_auth 并更新认证状态

绑卡流程

统一从 bindBankCard 入口触发；渠道内部可按规则决定是否先执行 openAccount。

支付流程

1. 创建支付单（createPay）
2. 用户确认支付（confirmPay，按渠道能力执行）
3. 异步回调更新状态
4. 必要时人工查询补偿（queryPay）

提现流程

1. 创建提现申请（写入 tian-third-withdrawals）
2. 调用渠道提现接口
3. 接收提现回调或主动查询
4. 更新申请状态与到账信息

回调地址与参数规范

统一通过 paymentNotifyUrl(type, module, thirdParty) 生成回调地址。

参数语义：

• type：回调类型，例如 wxpay、alipay、bankcard、third_party
• module：业务模块，例如 mall、score、onboarding、bankcard、withdraw
• thirdParty：渠道编码，例如 payeasenet

建议：

• 非订单型第三方回调（如入网、绑卡）统一使用 type = third_party
• 回调处理成功后返回渠道要求的成功标识（如部分渠道要求 SUCCESS）

核心数据归属

• uni-id-users.realname_auth：实名基础资料
• tian-third-onboardings：渠道入网记录
• tian-third-user-banks：用户银行卡记录
• tian-third-withdrawals：提现申请与打款生命周期
• tian-third-callback-logs：回调原始报文和处理日志

依赖说明

• crypto
• md5-node

如果你新增了直接使用的 uni- 组件或模块，请同步更新：

• uni_modules/tian-third-payment/package.json 的 uni_modules.dependencies

常见问题

1. 为什么已经实名还可以编辑实名信息？

建议在前端和后端都加状态校验：当 realname_auth.auth_status 已通过时，实名页应只读。

2. 为什么回调重复触发？

多数支付渠道在未收到约定成功响应时会重试回调。请确认：

• 验签通过后及时返回渠道要求的成功响应
• 回调处理具备幂等能力

3. 为什么绑卡后状态不一致？

建议以渠道查询结果为准，并在管理端提供人工触发查询入口，处理网络抖动或异步延迟造成的状态偏差。

对接建议

• 生产环境务必启用 HTTPS
• 妥善保管私钥、证书和接口密钥，不要提交到仓库
• 渠道对 IP 白名单、签名算法、回调重试规则可能不同，请严格按渠道文档配置
• 上线前完成全链路测试：实名 -> 入网 -> 绑卡 -> 支付 -> 退款 -> 提现 -> 回调补偿

渠道文档（首信易）

• 开放平台：https://open.payeasenet.com
• 快速开发：https://open.payeasenet.com/API/fast_Docking.html
• 入网：https://open.payeasenet.com/API/Declaration/declaration_split_new.html
• 绑卡：https://open.payeasenet.com/API/AgreementPay/Tiedcards.html
• 预下单：https://open.payeasenet.com/API/AgreementPay/TOrderAPI.html
• 退款：https://open.payeasenet.com/API/RefundAPI.html
• 代付提交（提现相关）：https://open.payeasenet.com/API/transferDomestic/transferDomestic_single_order.html

如果你需要新增其他支付渠道，建议先保持以下接口集合一致，再逐步补齐实现：

• openAccount
• parseOnboardingNotify
• bindBankCard
• resendBindCardCode
• confirmBindBankCard
• queryBindBankCard
• unbindBankCard
• createPay
• confirmPay
• queryPay
• refund
• queryRefund
• cancelPayOrder
• createWithdraw
• queryWithdraw
• parsePayNotify
• parseWithdrawNotify
• parseBankCardNotify