支付宝支付

最近更新时间：2023.9.21

1. 产品介绍

1.1 简介

斗拱为手机、平板、POS等智能终端的APP提供支付服务接口。斗拱收款、查询、结算、对账的完整流程服务。

汇付支付支持在主流应用市场完成认证的移动端应用APP接入支付功能。APP接入支付后，商户通过斗拱支付接口调用支付宝支付完成收款需求。目前支持手机系统有：IOS（苹果）、Android（安卓）。

1.2 应用场景

客户拥有自己的一个APP，为了使APP接入支付功能实现商业上的闭环，商户APP跳转支付宝成交易。

支付宝APP 支付可通过如下两种方式实现，核心是获取支付宝给的“凭证”。

• 通过支付宝扫码实现（Native支付）：参见本文3.3.1-支付宝NATIVE支付。
• 通过支付宝手机网站（JS支付）实现：参见本文3.3.2-支付宝JS支付（利用支付宝JS实现APP支付，需准备一个支付宝小程序）。

支付宝手机网站（JS）支付页面

可以通过斗拱演示APP体验了解支付宝支付在演示APP中的效果;下图是演示APP下载的链接。

2. 接入前准备

2.1 商务准备

1. 客户首先要有APP，APP已经在公开市场上架

2. 选择接入模式

3. 直签模式：指商户与汇付直接签约。具体流程：商户完成协议签署后，将准备好的入网材料提供给汇付销售人员，由汇付销售人员发起商户入网申请，待审核通过入网成功后，商户联系人将收到短信通知控台账号及密码。

4. 服务商模式：指服务商与汇付签约，服务商通过接口或控台方式完成商户入网。具体流程：服务商完成协议签署后，将准备好的入网材料提供给汇付销售人员，由汇付销售人员发起服务商入网申请，待审核通过入网成功后，服务商联系人将收到短信通知控台账号及密码。

5. 在斗拱完成商户进件入网

   1. 直签模式：已有汇付销售人员申请开通，商户无须另行操作；
   2. 服务商模式：
      1. 控台入网：参考服务商控台进件流程，渠道商接入指引；
      2. API入网：企业商户调用企业商户基本信息入驻接口 、小微商户调用个人商户基本信息入驻接口 完成开户、绑卡、结算配置。

6. 选择接入功能并准备相关材料

   1. 支付宝支付；

2.2 对接准备

第一步：密钥获取

联调之前需要先获取公私钥，参见公私解钥参数获取说明；

第二步：公共参数获取

登录服务商/商户控台后，可在开发设置-开发者信息中，获取sys_id，product_id参数信息;

第三步：业务开通及配置

• 服务商模式：

步骤一：服务商功能及权限开通。服务商通过线下签约方式申请支付宝功能，汇付运营人员在审核好服务商资料之后，为服务商开通相关支付功能，及费率配置。

步骤二：为商户开通功能及权限。服务商权限及费率配置完成后，服务商可在服务商控台为下属商户申请开通相关支付功能，或通过调用 商户业务开通 接口开通。具体流程请参考商户进件说明。

•  直签商户：

与客户经理确认已开通功能及相关费率配置。

3. 开发指引

3.1 对接规范

调用汇付接口，均采取POST形式提交，数据格式统一为JSON格式，相关SDK及签名方法见链接：

SDK示例：Java SDK

加签验签：v2版接口加签验签

3.2 业务开发配置

商户的APP需要通过拉起支付宝手机网站支付完成支付操作

3.2.1 支付宝侧接入准备：

1. 如选择支付宝native支付模式，无需提前准备；
2. 如选择支付宝JS支付模式，需要申请一个支付宝小程序并获取app_id；

3.2.2 斗拱侧准备:

1. 商户支付宝业务及费率已配置；（如已与客户经理确认，该步骤可忽略）

查询方式

1）服务商控台：【商户信息】【查看】【商户变更】【业务信息】【基础支付】

2）商户控台：【我的信息】

2. 支付宝实名认证状态已完成，实名认证状态显示已授权（支付宝侧实际完成即可，斗拱控台可能存在状态更新不及时）

查询方式

1）服务商控台：【商户信息】

2）通过支付宝实名认证状态查询接口来确认相关配置。

3.3 系统调用流程

3.3.1 NATIVE支付方式接入流程

此种方式的主要原理是：通过拉起支付宝APP 然后调用支付宝内said为10000007的扫码功能来发起支付，下单获取支付payinfo信息

接入步骤说明：

第一步：调用 聚合正扫 接口时trade_type: A_NATIVE(支付宝正扫)

第二步：前端拿到服务端返回的payinfo信息中的qr_code，在 APP 内 通过打开第三方APP的方式打开此URL

第三步：取出接口返回的qr_code，在 APP 内 通过打开第三方APP的方式打开如下URL

第四步：获取终态，客户支付完成后汇付会将支付结果推送到客户异步地址，如果长时间未收到异步结果可以调用扫码交易查询接口查询交易状态

示例：

alipays://platformapi/startapp?saId=10000007&qrcode=https://qr.alipay.com/bax02911brluc2xieoph6001复制代码复制失败复制成功

Android 示例代码：

    // 固定前缀
    String topic = "alipays://platformapi/startapp?saId=10000007&qrcode=";
    // 从汇付正扫接口获取的参数（以下值仅为示例）
    String qrcodeUrl = "https://qr.alipay.com/bax02911brluc2xieoph6001"
    // 字符串拼接
    String jumpUrl = topic + qrcodeUrl;
    // 按以上示例拼接得出结果
    // jumpUrl 为 alipays://platformapi/startapp?saId=10000007&qrcode=https://qr.alipay.com/bax02911brluc2xieoph6001
    Intent intent = new Intent();
    intent.setAction("android.intent.action.VIEW");
    // jumpUrl 为先前示例中拼装的 url
    Uri contentUrl = Uri.parse(jumpUrl);
    intent.setData(contentUrl);
    activity.startActivity(intent);复制代码复制失败复制成功

IOS示例代码：

 [[UIApplication sharedApplication]openURL:[NSURL URLWithString: jumpUrl]];复制代码复制失败复制成功

注意事项：

a.系统会弹出是否允许打开支付宝，点击允许，跳转支付宝进行支付，此种方式没有考虑用户没有装支付宝的情况。

b.如需考虑未安装支付宝的情况，APP端可使用 webview，加载聚合正扫接口返回的链接（例：https://qr.alipay.com/bax02911brluc2xieoph6001） 此种方式，如未安装支付宝客户端，会跳转到支付宝下载页面，引导用户安装下载。

c.以上部分是在APP为原生开发的前提下，RN的方式参考以下示例，Union App开发的可参考以上实现思路来实现，汇付无具体代码案例。

d.React Native方式可参考如下

    linkurl = 'alipays://platformapi/startapp?saId=10000007&qrcode='+ {URL}
    Linking.openURL(linkurl);复制代码复制失败复制成功

3.3.2 JS支付方式接入流程

此种方式的主要原理是：通过拉起支付宝APP，然后跳转到对应支付宝小程序中完成支付。

接入步骤说明：

第一步：APP端打开第三方APP的方式打开如下URL

alipays://platformapi/startapp?appId=app_id&page=page_path"复制代码复制失败复制成功

其中appid 为在支付宝侧申请的小程序appid，page_path 为跳转过去的小程序页面路径

第二步：获取 buyer_id，即付款用户的支付宝 user_id，详情参考支付宝官方文档： [用户授权](https://opendocs.alipay.com/mini/introduce/authcode#第一步：客户端获取 authcode)        

1. 小程序客户端内获取 authorization_code 示例：

    my.getAuthCode({
    scopes: ['auth_user'],
    // 主动授权：auth_user，静默授权：auth_base。或者其它scope。如需同时获取用户多项授权，可在 scopes 中传入多个 scope 值。
    success: (res) => {
            if (res.authCode) {
            // 认证成功
            // 调用自己的服务端接口，让服务端进行后端的授权认证，并且利用session，需要解决跨域问题
            my.request({
                url: 'https://isv.com/auth', // 该url是您自己的服务地址，实现的功能是服务端拿到authcode去开放平台进行token验证
                data: {
                authcode: res.authCode,
                },
                success: () => {
                // 授权成功并且服务器端登录成功
                },
                fail: () => {
                // 根据自己的业务场景来进行错误处理
                },
            });
            }
        },
    });复制代码复制失败复制成功

2. 商户服务端获取 access_token、user_id

服务器端调用 alipay.system.oauth.token(换取授权访问令牌) 接口换取授权访问令牌，开发者可通过获取到的 auth_code 换取 access_token（授权令牌） 和 user_id（用户支付宝 ID）。

auth_code 作为换取 access_token 的票据，每次用户授权完成，回调地址中的 auth_code 将不一样，auth_cod 只能使用一次，一天未被使用自动过期。

    AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
    AlipaySystemOauthTokenRequest request = new AlipaySystemOauthTokenRequest();
    request.setGrantType("authorization_code");
    request.setCode("4b203fe6c11548bcabd8da5bb087a83b");
    AlipaySystemOauthTokenResponse response = alipayClient.execute(request);
    if(response.isSuccess()){
        System.out.println("调用成功");
    } else {
        System.out.println("调用失败");
    }复制代码复制失败复制成功

参见：https://opendocs.alipay.com/mini/00g4c1

第三步：商户小程序服务端调用汇付 聚合正扫 接口时trade_type: A_JSAPI (支付宝JS)，获取支付信息，汇付下单成功会同步返回支付信息中包含tradeNO。

第四步：唤起收银台支付

在小程序端使用 tradeNO，调用 my.tradePay 接口唤起支付宝收银台，引导用户完成支付。详情参见支付宝官方说明： 小程序唤起收银台

    my.tradePay({
        tradeNO: '2017111521001104105336677922',
        success: function(res) {
          my.alert({
           content: JSON.stringify(res),
         });
        },
        fail: function(res) {
        my.alert({
          content: JSON.stringify(res),
          });
       },
    });复制代码复制失败复制成功

第五步：获取终态

客户支付完成后汇付会将支付结果推送到客户异步地址，如果长时间未收到异步结果可以调用扫码交易查询接口查询交易状态；

聚合正扫接口需关注以下字段：

同步返回关注以下字段：

异步返回关注以下字段：

3.3.3 退款流程

完整的交易流程还要包括退款。由于用户或者商户的原因需要退款时，商户可以通过本接口将支付款退还给用户，退款成功资金将原路返回。参见扫码交易退款接口；

关注以下请参：

• 原交易请求流水号、原交易全局流水号、原交易支付宝的商户单号三选一即可；
• 退款金额不能大于交易金额；由于接口支持多次部分退款，多次退款场景下退款总额仍不能高于交易金额；
• 退款也是以异步返回的成功或失败状态为最终结果；
• 一些特殊场景下退款时效可能比较长，注意接口描述文档中的退款时效说明；

3.3.4 对账流程

为了满足商户财务的对账需求，斗拱提供了对账功能。

方案一：控台下载；

方案二：接口获取；参见交易结算对账单查询接口

• 接口下载的对账文件包括以下四类：
  • 日对账单类型：包括日结算对账单、日分账对账单、日出金对账单；
  • 日交易数据：主要是各种支付交易记录；
  • 月结算对账单：按月汇总的结算对账单；
  • 月交易数据：按月汇总支付交易记录；

3.3.5 异步通知

针对交易结果，汇付会通过异步消息的方式通知客户系统。 

调用汇付接口时上送的异步通知地址为http/https路径：服务器为POST回调，默认超时时间为5秒，超时后会重试3次；不支持HTTP重定向；服务器对应答不是200~300之间的错误，会默认重试3次；异步通知服务器对HTTPS不认证验签和ALLOW_ALL_HOSTNAME_VERIFIER；如商户自定义通知端口，请使用8000-9005内端口，否则无法通知；URL 上请勿附带参数；异步回调请求编码集为：UTF-8；收到通知后请返回状态码“200”,响应异步通知。

注意事项：

同样的异步消息可能会通知多次，因此接收异步消息的处理需做好幂等，保障多次接收到同样的消息处理后结果不变。

在实现异步消息接收的同时，都建议您在重要的业务环节，通过反查接口确认 非终态 支付订单的状态，以保证在发生异步消息延迟或无法送达情况下的支付结果一致性。

详见异步通知使用说明。

4. API列表

5.常见问题

1. 支付时，接口报错:”当前商户需补齐相关资料后，才可进行相应的支付交易 ”

问题原因：此错误一般是商户还没有完成实名认证。

解决方案：完成支付宝实名认证

1).渠道商控台进行实名认证，菜单如图：

2).扫拓展码进行实名验证（可联系汇付人员指导）

3).通过接口进行实名认证：

实名认证接口：https://paas.huifu.com/partners/api/#/shgl/shjj/api_shjj_zfbsmrz

2. 支付宝实名认证返回：参数有误参数不正确： ILLEGAL_PARAMETER：商户smid已完成认证

已线下完成实名认证，无需再次实名。

3. 支付接口调用报错：“resp_desc”：“数据权限认证失败”

问题原因：商户信息校验没有通过。

解决方案：

1）检查报文中的产品号（product_id）是否填写正确;

2）检查报文中的系统号（sys_id）和商户号（huifu_Id） 从属关系是否正确。

4. 为什么交易成功以后会收到 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