快捷支付
最近更新时间：2023.9.16
1. 产品介绍
1.1 简介
持卡人无需登录网上银行，可直接输入卡面信息及持卡人身份信息。根据安全规则通过验证银行预留的手机接收校验码完成签约或支付，是一种便捷、快速、安全的付款方式，主要用于PC网站或移动端银行卡支付。
1.2 应用场景
商户如果想在自己的业务场景中摆脱对微信、支付宝的依赖，获取用户信息以便提供更好的服务可以选择快捷。或者将快捷深度融合到自己的业务场景中，比如整合自己的积分、营销服务等，可以选择快捷。斗拱提供了两种接口模式：
- 纯接口模式：包括绑卡、短信预校验、支付申请、支付确认等一系列接口，可以灵活地打造操作流程整合进业务流程中。
- 带页面的快捷接口，一个接口拉起支付页面完成整个支付流程，简单方便。
可以通过斗拱演示体验了解快捷支付在PC网站、APP、H5页面中的效果。
2. 接入前准备
2.1 商务准备
-
选择接入模式
-
直签模式：指商户与汇付直接签约。具体流程：商户完成协议签署后，商户需要准备好入网材料提供给汇付销售人员，汇付收到后会尽快为商户发起入网申请，待审核通过入网成功后，商户联系人将收到短信通知控台账号及密码。
-
服务商模式：指服务商与汇付签约，服务商通过接口或控台方式完成商户入网。具体流程：服务商完成协议签署后，服务商需要准备好入网材料提供给汇付销售人员，汇付收到后会尽快为服务商发起入网申请，待审核通过入网成功后，服务商联系人将收到短信通知控台账号及密码。
-
客户要准备好线上业务场景，快捷支付可以集成到PC网站、APP、H5页面的线上场景中。
-
在斗拱完成商户进件入网
- 直签模式：已有汇付销售人员申请开通，商户无须另行操作；
- 服务商模式：
- 控台入网：参考服务商控台进件流程，渠道商接入指引；
- API入网：企业商户调用企业商户基本信息入驻接口 、小微商户调用个人商户基本信息入驻接口 完成开户、绑卡、结算配置。
-
选择接入功能并准备相关材料
- 快捷支付能力：
- 直签模式：联系汇付销售人员申请开通，商户无须另行操作；
- 服务商模式：联系汇付销售人员申请开通服务商快捷支付权限，开通后给予所属商户开通相关权限；
- 快捷支付能力：
2.2 对接准备
第一步：密钥获取
联调之前需要先获取公私钥，参见公私解钥参数获取说明；
第二步：公共参数获取
登录服务商/商户控台后，可在开发设置-开发者信息中，获取sys_id，product_id参数信息；（如控台未展示，请联系对接群内汇付技术助手提供）
第三步：业务开通及配置
直签商户联系销售即可；
- 控台开通
服务商控台【商户管理】【信息查询】【商户信息（新）】【业务信息编辑】【支付功能】开通快捷支付、配置相关费率
- 接口开通
调用 商户业务开通 接口开通快捷支付。具体流程请参考API文档，商户进件。
3. 开发指引
3.1 对接规范
调用汇付接口，均采取POST形式提交，数据格式统一为JSON格式，相关SDK及签名方法见链接：
SDK示例：Java SDK
加签验签：v2版接口加签验签
3.2 确认业务配置
控台查询快捷支付是否配置完成
- 通过服务商控台【商户信息查询】【产品信息TAB页面】查看【快捷】
- 商户控台【我的信息】
- 通过商户详细信息查询接口来确认相关配置。
3.3 系统调用流程
3.3.1 交易流程
- 页面模式：调用快捷支付页面版接口，由于流程已封装不再描述；可进行斗拱演示体验，了解快捷支付在PC网站、APP、H5页面中的效果。
- 纯接口模式：
由于商户业务场景的差异，上图描述的只是快捷的标准流程，具体流程商户在不变更操作顺序的情形下可以结合实际调整。
接入步骤说明：
- 快捷支付前需要用户先完成绑卡，绑卡流程如下：
- 快捷支付流程分为两阶段；
- 商户会跳到业务系统页面。
快捷绑卡申请接口
入参需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| order_id | 订单号 | Y | 绑卡申请订单号 |
| out_cust_id | 商户用户id | Y | 用户在商户侧注册商户生成的用户号；同一用户不要反复注册不同的用户id； |
| card_id | 银行卡号 | Y | 需要密文传输，使用汇付RSA公钥加密(加密前64位，加密后最长2048位） |
| card_name | 银行卡开户姓名 | Y | 需要密文传输，使用汇付RSA公钥加密(加密前64位，加密后最长2048位） |
| cert_id | 银行卡绑定身份证 | Y | 需要密文传输，使用汇付RSA公钥加密(加密前64位，加密后最长2048位） |
| card_mp | 银行卡绑定手机号 | Y | 需要密文传输，使用汇付RSA公钥加密(加密前64位，加密后最长2048位） |
| vip_code | CVV2 | C | 信用卡交易专用需要密文传输。 |
| expiration | 卡有效期 | C | 信用卡交易专用，格式：MMYY，需要密文传输； |
| dc_type | 卡的借贷类型 | N | C:信用卡,D:借记卡,S:准贷记,U:未知卡； |
| protocol_no | 挂网协议编号 | C | 授权信息(招行绑卡需要上送)； |
快捷绑卡确认接口
入参需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| order_id | 订单号 | Y | 快捷绑卡申请接口的入参绑卡申请订单号order_id |
| verify_code | 验证码 | Y | 短信验证码 |
返参需关注字段：
| 参数 | 中文名 | 说明 |
|---|---|---|
| trans_status | 交易状态 | 绑卡状态，I:初始化,P:处理中,S:成功,F:失败 |
| cust_id | 用户号 | 绑卡成功后会获取用户客户号，参见快捷绑卡确认接口/一键绑卡接口的返参cust_id字段； |
| token_no | 绑卡序列号 | 后续快捷支付以token_no代表已绑定的卡 |
快捷支付申请
入参需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| card_bind_id | 绑卡id | Y | 绑卡成功后会获取绑卡id，参见快捷绑卡确认接口/一键绑卡接口的返参token_no字段； |
| user_huifu_id | 用户客户号 | Y | 绑卡成功后会获取用户客户号，参见快捷绑卡确认接口/一键绑卡接口的返参cust_id字段； |
| order_type | 订单类型 | N | P：支付; R：充值, 默认：P |
| time_expire | 订单失效时间 | N | 格式：yyyyMMddHHmmss,注：工商银行需传90min以上方能成功 |
返参需关注字段：
| 参数 | 中文名 | 说明 |
|---|---|---|
| avoid_sms_flag | 免短标签 | 如是 3，则无需调用确认接口 |
快捷支付确认
入参需关注以下字段：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| sms_code | 短信验证码 | Y | 用户提供6位短信验证码； |
异步返回关注以下字段：
| 参数 | 中文名 | 说明 |
|---|---|---|
| trans_stat | 交易状态 | I:处理中(初始化)，P：处理中，S：成功，F：失败； |
| acct_stat | 账务状态 | 可能因为手续费不足的原因存在交易成功账务失败的情况。这种情况可以联系汇付运营人员解决； |
3.3.2 退款流程
完整的交易流程还要包括退款。由于用户或者商户的原因需要退款时，商户可以通过本接口将支付款退还给用户，退款成功资金将原路返回。
参见线上交易退款接口；
关注以下请参：
| 参数 | 中文名 | 必填 | 说明 |
|---|---|---|---|
| org_req_date | 原交易请求日期 | Y | 用户发起支付的日期 |
| org_req_seq_id | 原交易请求流水号 | C | 商户系统发给斗拱的指令流水号 |
| org_hf_seq_id | 原交易全局流水号 | C | 汇付生成的系统流水号 |
| ord_amt | 申请退款金额 | Y | 退款金额<=原交易金额 |
- 原交易请求流水号、原交易全局流水号、原交易微信支付宝的商户单号三选一即可；
- 退款金额不能大于交易金额；由于接口支持多次部分退款，多次退款场景下退款总额不能高于原交易金额；
- 退款也是以异步返回的成功或失败状态为最终结果；
- 一些特殊场景下退款时效可能比较长，注意接口描述文档中的退款时效说明；
3.3.3 对账流程
为了满足商户财务的对账需求，斗拱提供了对账功能。
方案一：控台下载；
方案二：接口获取；参见交易结算对账单查询接口
- 接口下载的对账文件包括以下四类：
- 日对账单类型：包括日结算对账单、日分账对账单、日出金对账单；
- 日交易数据：主要是各种支付交易记录；
- 月结算对账单：按月汇总的结算对账单；
- 月交易数据：按月汇总支付交易记录；
3.3.4 异步通知
针对交易结果，汇付会通过异步消息的方式通知客户系统。
调用汇付接口时上送的异步通知地址为http/https路径：服务器为POST回调，默认超时时间为5秒，超时后会重试3次；不支持HTTP重定向；服务器对应答不是200~300之间的错误，会默认重试3次；异步通知服务器对HTTPS不认证验签和ALLOW_ALL_HOSTNAME_VERIFIER；如商户自定义通知端口，请使用8000-9005内端口，否则无法通知；URL 上请勿附带参数；异步回调请求编码集为：UTF-8；收到通知后请返回状态码“200”,响应异步通知。
注意事项：
同样的异步消息可能会通知多次，因此接收异步消息的处理需做好幂等，保障多次接收到同样的消息处理后结果不变。
在实现异步消息接收的同时，都建议您在重要的业务环节，通过反查接口确认 非终态 支付订单的状态，以保证在发生异步消息延迟或无法送达情况下的支付结果一致性。
详见异步通知使用说明。
4. API列表
| 类型 | 功能 | 描述 |
|---|---|---|
| API | 快捷支付页面版 | 快捷支付三合一页面版，只需一次短信验证码，系统自动完成绑卡支付 |
| API | 快捷绑卡申请接口 | 绑卡流程第一步 |
| API | 快捷绑卡确认接口 | 绑卡流程第二步 |
| API | 快捷解绑接口 | 解绑卡 |
| API | 快捷绑卡查询 | 查询已绑定的卡 |
| API | 快捷支付申请接口 | 商户系统调用该接口发起快捷支付申请，斗拱平台会向持卡人在银行预留的手机号发送短信验证码， 支持营销补贴功能 |
| API | 快捷支付确认接口 | 商户系统调用快捷支付确认接口，上送短信验证码，完成支付。 |
| API | 线上交易查询接口 | 查询单笔线上交易状态及明细 |
| API | 线上交易退款接口 | 支持线上交易全额或部分退款 营销补贴退款：支持全额退款、银行卡退款，不支持单独退补贴金额 |
| API | 线上退款查询接口 | 查询单笔线上退款状态及明细 |
| API | 电子回单查询 | 查看、下载快捷支付交易的回单 |
5.常见问题
- 【快捷绑卡申请】接口报错：“resp_code”：“00000003”，“resp_desc”：“已超过最大查询次数或操作过于频繁”
快捷绑卡要素验证，连续失败 3 次以上。
解决方案
核实要素确实没有问题，可 24 小时后再发起重试。
- 支付接口调用报错：“resp_desc”：“数据权限认证失败”
问题原因：商户信息校验没有通过。
解决方案：
1）检查报文中的产品号（product_id）是否填写正确;
2）检查报文中的系统号（sys_id）和商户号（huifu_Id） 从属关系是否正确。
- 为什么交易成功以后会收到 2 条异步通知？
2条异步通知分别是 交易异步 跟 账务异步，用 notify_type 字段区分。
1). 交易异步情况
notify_type='1'，trans_stat='F' 时，不推送账务异步
notify_type='1'，trans_stat='S' 时，会推送账务异步
2). 账务异步情况：
notify_type='2'，trans_stat='S'，acct_stat='S' 表示交易成功-入账成功
notify_type='2'，trans_stat='S'，acct_stat='F' 表示交易成功-入账失败（非正常情况，可联系汇付技术人员确认排查）
更多问题详见斗拱开发者社区：https://service.dougong.net/t/qa
