接入指南（必读）

接入流程 & 接口URL

第一步：下载证书

  • 开通测试商户后，开发者可以在收到的邮件中，点击链接地址，下载证书。请参考：开发说明&DEMO->加解签&DEMO-> 证书下载操作指引。
  • 注：邮件默认发送主联系人，会有3封：分别是含证书下载链接的邮件、含控台地址用户名和商户客户号子账户号等信息的邮件、以及一封含联调进度表和FAQ及证书操作指引的邮件，请联系贵司主联系人邮箱查看。
_images/cfca_mail.png
证书 用途
**********.pfx 用于加签 API 的请求参数
**********.cer 用于解签 API 的返回参数

第二步：调用接口URL

开发者可以参考 接口调用DEMO 和 开发者开放平台 进行对接测试，技术接入前可以浏览：接入指南(必读)-> 接口调用顺序 (适合不同场景) 和 对接过程中常见问题 ，同时请仔细阅读接口文档里的内容。

联调测试请求 URL https://apptrade.testpnr.com/api/merchantRequest

注：其中商户文件上传和下载两个接口的请求URL为：https://apptrade.testpnr.com/api/fileMerchantRequest

第三步：生产上线

  • 联调测试完成后，请填好联调进度表发给我司技术审核，审核通过后联系我司商务销售申请开通生产商户客户号。
  • 开通生产商户后，请开发者注意修改配置生产证书、生产证书秘钥、商户客户号和接口调用地址。
生产请求 URL https://apptrade.cloudpnr.com/api/merchantRequest

注：其中商户文件上传和下载两个接口的请求URL为：https://apptrade.cloudpnr.com/api/fileMerchantRequest

接口调用顺序（适合不同场景）

场景只列举了常用接口，本系统还有很多接口，详细请看左侧分类菜单中的接口名称和详细介绍。

快捷支付

  • 注：可根据实际业务需要增删其中的接口，自由组合。
  • 如：使用以下顺序1-2-3-6-7、4-12、1-10-11等，或直接使用一个8或9完成快捷支付的场景。
序号 快捷交易场景接口调用顺序 备注说明
1 101个人开户接口 开户得到user_cust_id和acct_id备用
2 111绑卡短信发送接口 用于快捷绑卡前短信发送（需配合103接口、114接口、115接口一起使用）
3 103绑卡绑卡接口 绑定快捷卡（注：有页面，且该接口订单号order_id需与111绑卡短信发送接口的订单号order_id一致）
4 812快捷绑卡代开户接口 开户+快捷绑卡二合一接口（纯接口API版，无页面，仅支持借记卡。注：单卡模式下，该接口绑定快捷卡时会自动将这个卡同时绑为取现卡），需调2次，详见接口说明
5 816前台快捷绑卡代开户接口 开户+快捷绑卡二合一接口（有页面。注：单卡模式下，该接口绑定快捷卡时会自动将这个卡同时绑为取现卡）
6 112快捷支付短信发送接口 用于201快捷支付时短信发送（配合201接口一起使用，先调112接口再调201接口）
7 201快捷支付接口 快捷支付（注：有页面，且该接口订单号order_id需与112绑卡短信发送接口的订单号order_id一致）
8 206快捷支付WEB版接口 开户+快捷绑卡+快捷支付三合一接口（有页面，适合PC端），可无需通过上述单个接口分开调用来实现快捷支付功能
9 208快捷支付APP版接口 开户+快捷绑卡+快捷支付三合一接口（有页面，适合移动端），可无需通过上述单个接口分开调用来实现快捷支付功能
10 216快捷支付统合版短信发送 用于217统合版快捷支付时短信发送（配合217接口使用，先调216接口再调217接口）
11 217快捷支付统合版支付 绑卡+快捷支付二合一接口（有页面，注：该接口订单号order_id需与216接口订单号order_id一致）
12 850快捷支付后台版 快捷支付（注：纯接口API版，无页面，需调2次该接口，第一次step_flag传01发短信，第二次更换订单号并传验证码确认支付），biz_trans_id参数前后2次需保持一致
13 110短信发送接口 用于解绑快捷卡和代扣卡前的短信发送（非必须），解绑银行卡时也可根据实际场景决定是否需要该接口
14 105银行卡解绑接口 用于解绑快捷卡、代扣卡、取现卡
15 205退款接口 用于快捷、代扣、网银、微信支付宝的交易退款
16 212订单解冻接口 用于快捷、网银、微信支付宝交易中分账串中冻结订单的解冻
17 301交易状态查询接口 查询某笔交易的状态结果，可以应对网络不稳定没收到我司异步回调的极端情况
18 317用户基本信息查询接口 用于查询客户号user_cust_id、子账号acct_id等信息
19 318用户绑卡信息查询接口 用于查询用户的各种绑卡ID、卡号、手机号等信息
20 123商户文件下载接口 用于下载对账文件或收益文件

代扣

  • 注：可根据实际业务需要增删其中的接口，自由组合。
  • 如：使用以下顺序2-5-7、1-3-4-7、2-6-7等，来实现代扣的场景。
序号 代扣类交易场景接口调用顺序 备注说明
1 101个人开户接口 开户得到user_cust_id和acct_id备用
2 113消费类订单录入接口 用于消费分期录入的产品信息，如分期买手机
3 111绑卡短信发送接口 用于代扣签约绑卡前短信发送
4 115非消费分期代扣签约绑卡接口 非消费类代扣签约绑卡（有页面。注：需先调111绑卡短信发送接口，该接口订单号order_id需和111绑卡短信发送接口订单号一致）
5 817前台代扣绑卡代开户接口 开户+代扣绑卡二合一接口（有页面）
6 809后台代扣绑卡代开户接口 开户+代扣绑卡二合一接口（纯API接口版，无页面，需调2次该接口，第一次step_flag传01发短信，第二次更换订单号并传验证码确认支付），bind_trans_id参数前后2次需保持一致）
7 849签约代扣支付接口 实现代扣功能（纯API接口）
8 825直接代扣支付 无需开户绑卡，可直接实现代扣功能（注：需根据资质找商务申请开通）
9 105银行卡解绑接口 用户解绑快捷卡、代扣卡、取现卡
10 301交易状态查询接口 查询某笔交易的状态结果，可以应对网络不稳定没收到我司异步回调的极端情况
11 317用户基本信息查询接口 用于查询客户号user_cust_id、子账号acct_id等信息
12 318用户绑卡信息查询接口 用于查询用户的各种绑卡ID、卡号、手机号等信息
13 123商户文件下载接口 用于下载对账文件或收益文件

网银

  • 注：可根据实际业务需要增删其中的接口，自由组合。
  • 如：使用以下顺序1-6、3-4-6等，或直接使用6来实现网银支付的场景。
序号 网银交易场景接口调用顺序 备注说明
1 101个人开户接口 开户得到user_cust_id和acct_id备用（注：网银交易可以不用开户，若需分账给不同的对象可以调此接口开户）
2 102企业用户开户接口页面版 用于企业用户开户的接口，会弹出我们的页面，页面上上传营业执照、统一社会信用码等附件（注：网银交易可以不用开户，若需分账给不同的对象可以调此接口开户）
3 122商户文件上传接口 纯API后台接口，企业开户前先通过该接口上传营业执照、统一社会信用码等附件
4 125企业开户申请接口后台版 纯API后台接口，企业开户，无页面，调用该接口前先调122商户文件上传接口（注：网银交易可以不用开户，若需分账给不同的对象可以调此接口开户）
5 124个体工商户开户接口 用于个体户开户，纯后台API接口，无页面，调用该接口前先调122商户文件上传接口
6 204网银支付WEB版接口 跳转网银支付
7 205退款接口 用于快捷、代扣、网银、微信支付宝的交易退款
8 212订单解冻接口 用于快捷、网银、微信支付宝交易中分账串中冻结订单的解冻
9 301交易状态查询接口 查询某笔交易的状态结果，可以应对网络不稳定没收到我司异步回调的极端情况
10 303余额查询接口 用于查询客户号user_cust_id、子账号acct_id等信息
11 123商户文件下载接口 用于下载对账文件或收益文件

微信支付宝类

  • 注：可根据实际业务需要增删其中的接口，自由组合。
序号 微信支付宝类场景接口调用顺序 备注说明
1 101个人开户接口 开户得到user_cust_id和acct_id备用（注：微信支付宝交易可以不用开户，若需分账给不同的人可以调此接口开户）
2 209扫码支付接口 微信、支付宝扫码（有页面）
3 218微信支付宝APP支付 微信app唤起、支付宝统一下单、微信公众号、小程序、银联微信支付宝扫码（纯API接口，开发者需自己根据url生成二维码）
4 205退款接口 用于快捷、代扣、网银、微信支付宝的交易退款
5 212订单解冻接口 用于快捷、网银、微信支付宝交易中分账串中冻结订单的解冻
6 301交易状态查询接口 查询某笔交易的状态结果，可以应对网络不稳定没收到我司异步回调的极端情况
7 303余额查询接口 用于查询客户号user_cust_id、子账号acct_id等信息
8 123商户文件下载接口 用于下载对账文件或收益文件

取现&代发

  • 注：可根据实际业务需要增删其中的接口，自由组合。
  • 如：使用以下顺序1-2-5、3-5、6等，来实现取现或代付至用户银行卡的场景。
序号 取现&代发场景接口调用顺序 备注说明
1 101个人开户接口 开户得到user_cust_id和acct_id备用
2 104绑定取现卡接口 用于用户取现卡的绑定
3 811取现绑卡代开户接口 开户+取现绑卡二合一接口
4 203转账接口 从某个账户转账至另一个账户，如：从商户账户转账到用户账户，进而完成取现功能
5 202取现接口 取现到用户银行卡
6 213代发接口 代发/代付到用户银行卡（可不用开户和绑卡）
7 105银行卡解绑接口 用户解绑快捷卡、代扣卡、取现卡
8 301交易状态查询接口 查询某笔交易的状态结果，可以应对网络不稳定没收到我司异步回调的极端情况
9 303余额查询接口 用于查询客户号user_cust_id、子账号acct_id等信息
10 317用户基本信息查询接口 用于查询客户号user_cust_id、子账号acct_id等信息
11 318用户绑卡信息查询接口 用于查询用户的各种绑卡ID、卡号、手机号等信息
12 123商户文件下载接口 用于下载对账文件或收益文件

开发者开放平台

为提高开发者对接本系统效率，我们提供了自助联调开发平台和MockServer两大平台，可供开发者完成单个接口测试和多个接口逻辑测试。

自助联调开发平台

功能说明

本系统为开发者提供了自助对接测试接口的平台，开发者可以通过DEMO以及该平台完成接口对接测试，查看接口效果及各接口代码示例（目前支持java和php代码展示），以便减少在本地开发中出现的不必要的错误和问题。

自助联调测试平台的地址为：

自助联调开发平台 https://apppay.cloudpnr.com/h5/login.html

使用说明

1、开发者访问及注册自助联调开放平台并登陆。

2、申请商户客户号和证书（若已有商户客户号和证书可以跳过该步骤）。

3、进入 开发接入->自助联调 进行接口在线调试，可结合右方实例代码和 对接过程中常见问题 完成测试。

MockServer平台

功能说明

为屏蔽掉联调测试过程中出现的意外情况（如环境不稳定，宕机），无法得到成功返回等问题，同时方便开发者多次调不同接口以测试商户完整业务场景逻辑，我们提供了一种mock的方式（我方配置的规则），可以通过传指定参数，返回指定的结果。

MockServer系统的地址为：

MockServer接口地址 https://mock.testpnr.com/api/app_plus/npay/merchantRequest

使用说明

1、MockServer系统没有逻辑，也不做真实交易处理，仅接收商户根据我们指定的规则参数请求后返回指定的结果。

2、使用MockServer接口需要修改调用接口的请求地址（见上方地址），接口参数按实际接口文档上传参（规则内指定的参数除外）。

3、Mock规则说明：目前我们的匹配规则是指定mer_priv参数（若接口中有，详看下方规则参数）来实现返回指定结果，具体规则见下方，其他参数可按接口文档必传参数来填（目前不校验参数是否非法）。

  • 注：接口中有mer_priv参数的，一律以mer_priv为指定规则参数传参（其他参数无要求）。
规则参数 请求参数要求 根据规则参数返回的结果
mer_priv 1 交易成功
bind_card_id 1 交易成功
business_code 1 交易成功
  • 举例：如个人开户接口101，接口参数mer_priv填1，返回结果就是成功。（接口中其他参数可根据文档必传参数要求随便传值）

对接过程中常见问题

此处提供了在对接汇付接口测试过程中出现的一些常见问题和要求，请仔细阅读。

证书&DEMO问题

常见问题列表 出现该问题的原因
pfx证书从哪获取？ 请仔细阅读：接入指南（必读）->接入流程-> 第一步下载证书 ,已特别注明证书来源。
测试环境下载pfx证书连接，点击后收不到验证码？ 测试环境证书下载不会发送验证码，验证码可输入1111进行下载，生产环境按实际收到的验证码登陆。
pfx证书下载按钮点了没反映？ 如果是IE内核的浏览器，此时看下internet选项中->内容->证书是否含有NP开头字样的证书，如果有直接按证书下载指引导出即可，其他浏览器可以百度下类似internet选项证书的方式导出。
pfx证书点击下载过期？ 证书下载链接有时间限制，如过期请联系我司商务销售找中台重新发下。
DEMO程序运行报错加签失败、验签失败、证书非法等 1、请确保demo中的商户客户号mer_cust_id和证书及密码是否替换成贵司自己的商户客户号和证书及密码(一个商户号对应一个pfx证书)；
2、检查代码中验签注释部分商户号mer_id是否是固定值100001；
3、请确保是application/x-www-form-urlencoded方式请求；
4、jodd-http-5.0.2.jar这个jar包需和jodd-core-5.0.2.jar包配合使用；
5、调用的pfx和cer证书文件须是绝对路径；
请求报错：Error occured when checking params 此报错说明加签前的json串有异常，导致我方服务器解签失败而返回，请检查json串是否有问题。
php的demo命令行执行报错:parameter is null 请检查证书路径、密码、权限是否有问题，通常原因是没有读证书的权限。
phpDEMO报错Message:cfca_Initialize error:24578 初始化失败，请检查下服务器权限。
加签报错{code=999, message=系统异常,sign=null} 通常为证书问题，贵司开发者可以重新导入再导出证书，或者在我司技术群咨询。

接口问题

常见问题列表 出现该问题的原因
商户无此接口权限？ 请联系我司商务销售申请开通该接口权限。
测试环境个人开户失败？ 建议用真实身份证开户，身份证号首位请用1-5开头的。
测试环境短信验证码没收到？ 测试环境不会发送短信，短信验证码统一为111111。
快捷绑卡、代扣签约等后台调接口却返回html页面？ 此类接口，请用页面浏览器form表单方式提交，具体可参考接口文档中每个接口调用方式。
绑卡返回：MOCK要素未配置，或没有收到异步响应？ 请用指定的建设银行卡bin测试。建行：01050000 ，其中：
借记卡为：623251000000XXXX，XXXX为0000-9999之间
贷记卡为：436748010435XXXX，XXXX为0000-1000之间
分账串信息怎么填，分账串信息异常？ div_detail分账串表示分账对象，填谁，表示钱分给谁，即钱到谁的账户；in_cust_id和in_acct_id表示入谁的账户。
如果钱入给你们平台，就填你们平台商户客户号和子账号(这个是邮件发的)，如果钱分跟给用户，就填开户接口时返回的user_cust_id和子账号acct_id。
报错：支付手续费未配置？ 此报错说明该交易的手续费没有配置（借记卡支付、贷记卡支付、准贷记卡支付、微信支付宝交易等），请根据合同上的约定联系销售至中台配置费率。
测试环境首次支付失败？ 首次支付失败由于手续费金额不足（默认从商户平台扣收）导致的失败，请至商户控台进行网银充值（测试环境只仅支持兴业银行，2元以上），以免不够扣手续费而失败。
咨询手续费的问题 手续费的问题请联系贵司或者我司的商务销售，这是贵司与我司合作签合同或协议时双方约定的。