阅读对象

具有一定开发能力的开发人员。

接入前准备

通用代扣：

1. 确认是否已经成功签约通用代扣协议

2. 确认是否已经拿到接口技术文档（由支付宝技术支持提供）

3. 获取签约场景信息用于签约接口参数scene（INDUSTRY|CHARGE--缴费行业专用）（INDUSTRY|PUBLIC_SERVICE--公共服务行业专用）

信用代扣：

1. 确认是否已经成功签约信用代扣协议

2. 确认是否已经拿到芝麻信用授权信息buckleAppId（芝麻信用分配的商户AppId）和buckleMerchantId（芝麻信用分配的商户ID）

3. 确认是否已经拿到接口技术文档（由支付宝技术支持提供）

4. 获取签约场景信息用于签约接口参数scene（INDUSTRY|CHARGE--缴费行业专用）（INDUSTRY|PUBLIC_SERVICE--公共服务行业专用）

接口列表：

开始接入

接入场景介绍：代扣使用场景有手机app，wap站点，PC网站，扫码签约代扣（例如电视支付、物业出租房管理等），针对不同的使用场景，有不同的接入细节，此前先确定使用场景，选择适合自己的接入方式；

◆手机app场景：商户有自己的独立app，希望在独立app上对接支付宝的代扣服务

第一步：集成签约接口《支付宝个人协议页面签约接口（alipay.dut.customer.agreement.page.sign）》

1. 判断客户端是否安装有钱包，有则打开钱包的签约页面。

   判断方法：

   iOS ：判断scheme: alipays://是否存在 。

   android： 判断package name是否存在: com.eg.android.AlipayGphone。

2. 服务端对接支付宝个人协议页面签约接口（alipay.dut.customer.agreement.page.sign），根据文档要求，拼接得到签约URL；

    针对签约接口需要注意的点如下：

    a。业务参数产品码（product_code）的值：GENERAL_WITHHOLDING_P

    b。业务参数接入信息（access_info）的值：{"channel":"ALIPAYAPP"}

    c。业务参数签约场景（scene）的值；INDUSTRY|CHARGE或INDUSTRY|PUBLIC_SERVICE

    d。信用代扣需要传入业务参数芝麻信用授权信息（zm_auth_info）,具体信息参数芝麻信用分配的商户（AppIdbuckleAppId）和芝麻信用分配的商户ID（buckleMerchantId）现阶段需要向芝麻技术支持获取（通用代扣请忽略）

    ★扩展：业务参数商户签约号（external_sign_no）的使用，针对同一签约主体，同一用户有不同的签约场景需要签订多份协议，可以通过该参数控制

3. 对得到的整串URL参数进行encode，这个操作必须要做；

4. 将encode之后的URL拼到链接：”alipays://platformapi/startapp?appId=20000067&url=”之后，其中斜体内容不需要任何调整，将该链接从app端发起访问；

5. 签约成功之后跳回app：通过在请求参数return中设置scheme链接来完成回跳，

6. 签约完成，获取支付宝返回数据协议号，保存；

第二步：集成代扣接口《统一下单并支付接口（alipay.acquire.createandpay）》

完成用户签约之后，商户端就可以主动发起扣款，扣款确认方式有无需确认（即不需要用户有确认操作即可完成扣款）和短信确认（即需要用户完成短信确认方可完成扣款），扣款方式根据商户跟支付宝签订的协议而定；

1. 根据接口技术文档拼接http请求链接，其中需要注意如下：

    a。业务参数订单业务类型（product_code）的值：GENERAL_WITHHOLDING

    b。业务参数协议信息（agreement_info）中设置好参数协议号（agreement_no）的值：为第一步调用签约接口后支付宝返回的协议号；

    c。业务参数买家支付宝用户号（buyer_id）和动态ID（dynamic_id）不需要传值；

    d。业务参数订单支付超时时间（it_b_pay）的值：建议设置3~5m，该参数控制订单的失效时间，即如果设置为3m，那么发起代扣请求成功但是没有扣款成功的情况下该笔订单会在3分钟之后关闭，用户不再能支付；

    ★扩展：针对同一签约主体，同一用户有多份代扣协议的情况下，商户端可以通过订单号、用户userid和协议号关联区分；

2. 根据同步XML返回或者异步通知获取代扣数据，更新数据库，记录代扣数据；

第三步：根据需要集成余下接口；

 ◆扫码签约代扣：有独立设备可以展示二维码，供用户扫二维码即可完成个人协议签约

 第一步：集成签约接口《支付宝个人协议页面签约接口（alipay.dut.customer.agreement.page.sign）》

1. 服务端对接支付宝个人协议页面签约接口（alipay.dut.customer.agreement.page.sign），根据文档要求，拼接得到签约URL；

    针对签约接口需要注意的点如下：

    a。业务参数产品码（product_code）的值：GENERAL_WITHHOLDING_P

    b。业务参数接入信息（access_info）的值：{"channel":"ALIPAYAPP"}

    c。业务参数签约场景（scene）的值；INDUSTRY|CHARGE或INDUSTRY|PUBLIC_SERVICE

    d。信用代扣需要传入业务参数芝麻信用授权信息（zm_auth_info）,具体信息参数芝麻信用分配的商户（AppIdbuckleAppId）和芝麻信用分配的商户ID（buckleMerchantId）现阶段需要向芝麻技术支持获取（通用代扣请忽略）

    ★扩展：业务参数商户签约号（external_sign_no）的使用，针对同一签约主体，同一用户有不同的签约场景需要签订多份协议，可以通过该参数控制

2. 将URL中的请求参数做urlencode处理，示例如下：

    http://mapi.alipay.com/gateway.do?sign_type=MD5&zm_auth_info=%7B%22buckleAppId%22%3A%221000030%22%2C%22buckleMerchantId%22%3A%22268820000049398443659%22%7D&agreement_detail=%7B%22payToolSummaryDetails%22%3A%5B%7B%22payToolSummary%22%3A%22OSACCOUNT_DC_OSACCOUNT_DEFAULT%22%2C%22extInfo%22%3Anull%7D%5D%2C%22payToolInfoDetails%22%3Anull%2C%22quotaDetails%22%3Anull%7D&partner=2088011177463882&prod_properties=%7B%22AuthBizInfo%22%3A%7B%22platform%22%3A%22B2B%22%7D%7D&access_info=%7B%22channel%22%3A%22ALIPAYAPP%22%7D&sendFormat=normal&return_url=http%3A%2F%2Fapi.test.alipay.net%2Fatinterface%2Freceive_return.htm&sign=b3212f0fbcbcaec82fe70295005157bd&product_code=GENERAL_WITHHOLDING_P&external_sign_no=e8qdwl9caset5zugii2r7q0k8ikopxorcf&service=alipay.dut.customer.agreement.page.sign&scene=INDUSTRY%7CMEDICAL

3. 调用支付宝短链接申请接口（alipay.mobile.short.link.apply），生成短连接；（注意：该接口需要独立签约，可联系商务签约）

4. 将短连接绘制成二维码，在终端设备显示，供用户扫码；

5. 扫码成功，签约完成，得到签约结果，获取协议号，保存；

第二步：集成代扣接口《统一下单并支付接口（alipay.acquire.createandpay）》

完成用户签约之后，商户端就可以主动发起扣款，扣款确认方式有无需确认（即不需要用户有确认操作即可完成扣款）和短信确认（即需要用户完成短信确认方可完成扣款），扣款方式根据商户跟支付宝签订的协议而定；

1. 根据接口技术文档拼接http请求链接，其中需要注意如下：

    a。业务参数订单业务类型（product_code）的值：GENERAL_WITHHOLDING

    b。业务参数协议信息（agreement_info）中设置好参数协议号（agreement_no）的值：为第一步调用签约接口后支付宝返回的协议号；

    c。业务参数买家支付宝用户号（buyer_id）和动态ID（dynamic_id）不需要传值；

    d。业务参数订单支付超时时间（it_b_pay）的值：建议设置3~5m，该参数控制订单的失效时间，即如果设置为3m，那么发起代扣请求成功但是没有扣款成功的情况下该笔订单会在3分钟之后关闭，用户不再能支付；

    ★扩展：针对同一签约主体，同一用户有多份代扣协议的情况下，商户端可以通过订单号、用户userid和协议号关联区分；

2. 根据同步XML返回或者异步通知获取代扣数据，更新数据库，记录代扣数据；

第三步：根据需要集成余下接口；

充电桩先充电后付费流程参考示例：

手机app新用户注册引导签约代扣流程：

代扣失败处理流程：

常见问题

1. 个人和签约主体进行签约之后，可以解约吗？可以怎么解约？

可以进行解约，解约方式有2种，第一种：用户端在支付宝钱包的账户授权管理下的签约管理中进行解除协议或PC端账户管理里面进行解除协议；第二种：签约主体方集成支付宝解约接口进行解约；

2. 调用代扣接口发起代扣请求，发生扣款失败的情况怎么处理？

发起代扣请求扣款失败，分2种情况，第一种：发起代扣请求失败，支付宝交易库尚未记录该笔交易；第二种：发起代扣请求成功，但是由于某种原因导致扣款失败，即支付宝交易库已经创建该笔订单且订单状态为等待买家付款；

基于以上2种情况，建议：

a. 代扣请求参数中设置交易超时时间it_b_pay，建议可以设置为3~5m，为了保证代扣请求扣款失败的情况下，指定时间内将交易关闭（默认交易关闭时间为15天），避免用户打开支付宝钱包发现有未支付订单进行主动支付；

b. 调用收单查询接口查询订单状态，建议在it_b_pay时间之后发起查询，如果查到的交易状态是不存在或者交易关闭，则重新发起代扣指令，如果查到的交易状态是已支付，更新数据库，处理业务逻辑；

c. 如果发生重复扣款的情况，建议走收单退款接口将重复扣款的交易进行退款，但是用户体验原则，建议尽量避免重复扣款；

FAQ