产品接口

    协议相关：

            统一下单并支付页面接口-alipay.acquire.page.createandpay(首次扣款和签约合并)

            支付宝个人协议页面签约接口-alipay.dut.customer.agreement.page.sign(签约接口，如果使用统一下单并支付页面接口，则无需再单独调用签约接口)

            支付宝个人协议解约接口-alipay.dut.customer.agreement.unsign

            支付宝个人协议查询接口-alipay.dut.customer.agreement.query

            支付宝个人协议状态调整接口-alipay.dut.customer.agreement.status.adjust(通常不需使用)

            支付宝个人协议页面签约修改接口-alipay.dut.customer.agreement.page.sign.modify(通常不需使用)

            支付宝商户协议查询接口-alipay.dut.merchant.agreement.query(通常不需使用)

    扣款相关：

            统一下单并支付页面接口-alipay.acquire.page.createandpay(首次扣款和签约合并)

            统一下单并支付接口-alipay.acquire.createandpay(已签约后扣款使用)

            收单退款接口-alipay.acquire.refund

            收单查询接口-alipay.acquire.query

技术方案

      1、支付并签约流程

             

 

      2、签约流程

           

 

      3、查询协议流程

           

 

      4、解约流程

           

 

      5、已签约用户扣款流程

           

接口调用总体说明

    1、商户代扣适用于pc/电视扫码签约及App跳转签约两种场景。

         二者区别在于pc/电视场景，是把签约并支付接口(alipay.acquire.page.createandpay)做成二维码形式，由用户打开钱包扫码完成首次支付和签约。

         (注意，纯签约接口alipay.dut.customer.agreement.page.sign可以设置为在PC页面上签约，通过access_info参数)。

         App跳转签约场景是由商户app打开支付宝钱包app的签约页面，完成首次支付和签约(或签约)。签约成功后，后续扣款都由商户服务端调用统一下单并支付接口完成，无需用户在支付宝端输入支付密码确认。

    2、首次支付并签约(或签约)时，使用钱包调用统一下单并支付页面接口或签约接口(可用app跳转scheme方式打开钱包，或者由用户使用钱包扫描二维码)。用户需要在钱包内完成支付及签约。只有该操作需要用户在钱包页面内完成，其他接口都由商户服务端发起。

    3、商户通常会用到统一下单并支付页面(首次支付并签约)，个人协议解约，个人协议查询，统一下单并支付(已签约用户扣款使用该接口)4个接口。因为统一下单并支付页面接口能够同时完成签约和支付，所以无需单独调用支付宝个人协议页面签约(alipay.dut.customer.agreement.page.sign)接口，可以减少一步交互。

         如果不使用统一下单并支付页面接口进行签约，则需单独调用支付宝个人协议页面签约接口(alipay.dut.customer.agreement.page.sign)来完成签约。

    4、其它接口结合业务需求自行决定是否使用。

    5、用户支持一对多，即同一个商户下，同一个用户可以有多套签约关系。通过商户签约号和场景码参数来区分哪套协议。但要注意，如果签约时传入了签约号及场景参数，后续查询协议和解约时也必须传入。如果为了简单，可考虑只维护一套签约关系(再次签约会提示签约信息已存在)，无需传入签约号和场景。

    6、解约接口支持商户端解约及支付宝端解约(可关闭)，详见后面的 解约流程

首次支付并签约说明

    1、调用统一下单并支付页面接口(alipay.acquire.page.createandpay) ，参考 支付并签约流程。该接口集成了支付并签约功能，使用了该接口，则无需再使用单独签约接口。

    2、请求参数中：

       1>.买家参数无需传入(买家用户号，买家账号，买家信息) 。

       2>.订单业务类型(product_code)设为GENERAL_WITHHOLDING。

       3>.参数集成方式(integration_type) 设为ALIAPP(不论是app跳转还是pc/电视扫码都要这样设置)。

       4>. 请求来源地址(request_from_url) 设置app scheme，如果用户中途取消支付会返回该地址(唤起app)。

       5>.页面跳转同步通知页面路径(return_url) 设置为商户app scheme。签约成功后会把签约结果同步返回给客户端。

       6>.签约参数(agreement_sign_parameters)必须设置。其中，签约产品码(productCode)设为GENERAL_WITHHOLDING_P。签约成功后接收异步通知的地址(notifyUrl)需要传入，用来接收签约信息。如果需要支持一对多协议(同一个用户支持多个协议)，则需设置商户签约号(externalAgreementNo)，保持唯一，用来标示本次签约关系。同时还需设置场景(scene)参数。

            常见参考场景码：                        

INDUSTRY|LOTTERY	彩票行业
INDUSTRY|SOCIALIZATION	社交行业
INDUSTRY|MEDICAL	医疗行业
INDUSTRY|APPSTORE	电子商城行业
INDUSTRY|SUPERMARKET	超市行业
INDUSTRY|B2B_TICKET_AGENT	机票机构行业
INDUSTRY|CARRENTAL	租车行业
INDUSTRY|CAR_FINANCE	汽车金融
INDUSTRY|EDU_MULTIMEDIA	校园一卡通-多媒体
INDUSTRY|EDU_AUTODEPOSIT	校园一卡通-自动充值
INDUSTRY|CATERING	餐饮业
INDUSTRY|PURCHASE	采购业
INDUSTRY|REPAYMENT	信贷还款
INDUSTRY|TAOBAO_STORE	淘宝商城
INDUSTRY|CHARGE	收费行业
INDUSTRY|DIGITAL_MEDIA	数字传媒行业
INDUSTRY|GAME_CHARGE	网游行业
INDUSTRY|BADGE_CONSUMPTION	工牌消费
INDUSTRY|PARKING	停车行业
INDUSTRY|MOBILE	移动支付
INDUSTRY|TV	电视支付
INDUSTRY|FINANCE	金融行业
INDUSTRY|LEASE	租借行业
INDUSTRY|EDU	教育行业
INDUSTRY|VOICEPAY	语音支付
INDUSTRY|FOREX_PLAT_PURCHASE	境外平台采购
INDUSTRY|ALIPAYGO	ALIPAYGO
INDUSTRY|TICKET	票务行业

    3、签约成功后的异步通知内容参考支付宝个人协议页面签约接口(alipay.dut.customer.agreement.page.sign)接口文档中的异步通知。其中包含支付宝用户号（alipay_user_id）和协议号(agreement_no)。商户应该保存这些信息，以供后续解约，查询，扣款等接口使用，(如果有传入商户签约号及场景，也需保存)。

    4、签约时通常不需要短信验证，但如果支付宝风控检测到风险，会下发短信要求输入验证码。

         如果签约时，有效期未传入，默认长期有效。那么查询结果里，失效时间（invalid_time）返回的是2115年以后。

单独签约说明

    1、如果使用了签约并支付流程来完成签约，则无需单独调用该签约流程。独立签约接口(alipay.dut.customer.agreement.page.sign)。

    2、请求参数中，

        1>.签约产品码(product_code)设为GENERAL_WITHHOLDING_P。

        2>.接入信息(access_info)可以根据需要设置为PC页面签约或者通过钱包H5页面签约。

        3>.页面跳转同步通知页面路径(return_url) 设置为商户app scheme。签约成功后会把签约结果同步返回给客户端。

        4>.如果需要支持一对多协议(同一个用户支持多个协议)，则需设置商户签约号(external_sign_no)，保持唯一，用来标示本次签约关系。同时还需设置场景(scene)。

查询协议说明

    1、该接口调用场景由商户结合自身情况使用。可以在解约及扣款前调用来核实确认签约信息。也可以不调用，由商户签约及解约时(及支付宝端解约的异步通知)自行维护好签约关系。

    2、查询接口参数中：

        1>.如果签约时商户签约号及场景参数有设置，查询时也需设置，与签约时保持一致。否则查不到协议。

        2>.参数产品码(product_code) 设为GENERAL_WITHHOLDING_P

    3、查询接口返回<response><userAgreementInfo/> </response>，userAgreementInfo不存在子节点，可能的原因有：

        1>.用户没有签约，或者商户签约号external_sign_no传错。

        2>.用户已解约。

        3>.如果签约时有传商户签约号external_sign_no和场景码scene，那查询时也要传。

    4、签约号如果过期了，可以调用续签接口由用户续签。但需要确保支付宝账号也是相同 。如果无法保证，建议更换新的签约号签约。

解约说明

    1、解约有两种方式，参考图4。1>.是由商户调用支付宝个人协议解约接口(alipay.dut.customer.agreement.unsign)进行解约。2>.是由用户在支付宝钱包app或pc主站进行解约。

    2、支付宝个人协议解约接口(alipay.dut.customer.agreement.unsign)中请求参数：

        订单业务类型(product_code)设为 GENERAL_WITHHOLDING_P。

        如果签约时，传入了参数商户签约号(external_sign_no)和场景(scene)，则解约时也需传入。

    3、支付宝端解约入口可以在后台销售方案中指定是否开启。如果不开启，则只能由商户端提供解约功能。

        如果开启，请商户同时提供编码类型，签名类型和异步通知地址 这三个信息给业务经理，由其配置在合同中。提供的格式类似：

            UTF-8|MD5|https://www.xxx.com/ali_unsign_notify.html

            或 GBK|RSA|https://www.xxx.com/ali_unsign_notify.html

        后续支付宝端解约时会发送异步通知给商户地址。通知的内容格式请参考个人协议解约接口(alipay.dut.customer.agreement.unsign)中的异步通知格式。(测试异步通知可以运行该接口来测试)。

    4、目前也支持在支付宝端解约时跳转到商户解约页面，由商户引导完成相关业务处理。需要业务经理在销售方案配置跳转地址。该跳转仅是页面跳转，商户需要自行判断获取用户身份，确定签约的代扣协议。判断用户身份方式很多，可以提供账号登陆功能，也可以通过静默授权获取用户的uid，通过uid反查用户身份及协议，并展示给用户确认。授权产品文档：参考地址 （拼接授权页面链接url中scope设为auth_base即为静默授权）

已签约用户扣款说明

    1、已经签约过用户再次支付时由商户服务端调用《统一下单并支付接口(alipay.acquire.createandpay)》进行扣款，无需用户与支付宝交互。

    2、请求参数中，订单业务类型(product_code)设为 GENERAL_WITHHOLDING。

        参数buyer_id和dynamic_id无需设置，签约时返回的协议号传入到协议信息(agreement_info)中即可。

    3、如果用户没有在钱包中设置过支付顺序或者支付习惯，默认会按照如下顺序进行扣款(扣款顺序可能会变更，以实际为准)：

        营销工具，信用卡，余额，借记卡，余额宝。

        扣款时会按优先级去轮询各渠道，如果各渠道都不够支付则会报错。不会拆分金额用各渠道组合支付。

    4、通常调用扣款请求后会直接返回成功或者失败原因，必须以收到ORDER_SUCCESS_PAY_SUCCESS结果作为支付成功标示。如果返回了处理结果未知(UNKNOWN)状态或者SYSTEM_ERROR错误码或者ORDER_SUCCESS_PAY_INPROCESS，此时无法确认扣款成功或失败，需要依赖异步通知结果或者等待一段时间(如5分钟)再调用收单查询接口(alipay.acquire.query)去核实支付结果。

    5、签合同时可以配置单笔免密额度及单笔短信确认额度。如果只配置了单笔免密支付额度，则扣款金额超出该限额时，会直接报错。如果也配置了短信确认额度（需大于单笔免密额度），则当扣款金额超过单笔免密额度并小于短信确认额度时，支付宝会给用户发送短信，需要用户进行回复确认。具体配置可与业务经理沟通。当需要用户确认时，扣款接口会返回支付等待中(ORDER_SUCCESS_PAY_INPROCESS)状态，需要等待异步通知结果或者等待一段时间(短信确认过期时间是30分钟)后调用收单查询接口(alipay.acquire.query)去查询支付结果。

    6、如果因为余额不足等原因导致扣款失败，在用户支付宝账单中不会显示该笔未支付订单。扣款行为依赖商户主动调用。

    7、退款及查询接口请自行阅读文档：收单退款接口(alipay.acquire.refund)及收单查询接口(alipay.acquire.query)，逻辑很简单，此处不做详述。 

其他说明

    1、扣款接口_input_charset参数要用 GET方式传递。

    2、代扣签约的用户的支付宝账户必须是实名认证的。

    3、钱包签约页面提示不具有角色权限。因为需要钱包先登录，才能签约。如果用户已经登陆过还出现该情况，请重新注销再登录。这可能是因为支付宝的session没读到用户信         息

FAQ

关于此文档暂时还没有FAQ