开发者社区
社区提问意见反馈
开发者钉组织
扫描二维码
加入支付宝开发者钉组织
文档中心
网页&移动应用 
支付产品
当面付
订单码支付
app支付
手机网站支付
电脑网站支付
商家扣款
权限集列表
商家扣款(必选)
接入指南
api 列表
签约
支付
对账
相关资料
商家分账(可选)
预授权支付
刷脸付
支付 mcp 和插件服务
私域产品
公域产品
营销产品
资金产品
会员产品
信用产品
安全产品
广告产品
其他通用产品
开发 > 服务端 > 支付产品 > 商家扣款 >  >  >  >  > 支付宝个人协议页面签约接口
收藏
订阅更新
我的文档
设置
接入检测
即可查看检测结果)
若有未通过的接入检测项,接口将无法调通

接口说明

该接口是页面跳转接口,用于生成用户访问支付宝的跳转链接。请在服务端执行支付宝sdk中pageexecute方法,读取响应中的body()结果。该结果用于跳转到支付宝页面,返回到用户浏览器渲染或重定向跳转到支付宝页面。具体使用方法请参考 接入指南
支持用户在支付宝页面完成支付宝代扣协议的签约,目前只支持支付宝钱包h5页面场景。

公共请求参数

参数类型是否必选最大长度描述示例值
app_idstring必选32
支付宝分配给开发者的应用id
2014072300007148
methodstring必选128
接口名称
alipay.user.agreement.page.sign
formatstring可选40
仅支持json
json
return_urlstring可选256
http/https开头字符串
https://m.alipay.com/gk8nf23
charsetstring必选10
请求使用的编码格式,如utf-8,gbk,gb2312等
utf-8
sign_typestring必选10
商户生成签名字符串所使用的签名算法类型,目前支持rsa2和rsa,推荐使用rsa2
rsa2
signstring必选344
商户请求参数的签名串,详见签名
详见示例
timestampstring必选19
发送请求的时间,格式"yyyy-mm-dd hh:mm:ss"
2014-07-24 03:07:50
versionstring必选3
调用的接口版本,固定为:1.0
1.0
notify_urlstring可选256
支付宝服务器主动通知商户服务器里指定的页面http/https路径。
http://api.test.alipay.net/atinterface/receive_notify.htm
app_auth_tokenstring可选40
biz_contentstring必选
请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

业务请求参数

personal_product_code必选string(64)
【描述】个人签约产品码,商户和支付宝签约时确定,商户可咨询凯发app官方网站的技术支持。
【示例值】general_withholding_p
access_params必选accessparams
【描述】请按当前接入的方式进行填充,且输入值必须为文档中的参数取值范围。 扫码或者短信页面签约需要拼装http的请求地址访问中间页面,钱包h5页面签约可直接拼接scheme的请求地址
channel必选string(20)
【描述】目前支持以下值: 1. alipayapp (钱包h5页面签约) 2. qrcode(扫码签约) 3. qrcodeorsms(扫码签约或者短信签约)
【示例值】alipayapp
period_rule_params特殊可选periodruleparams
【描述】周期管控规则参数period_rule_params,在签约周期扣款产品(如cycle_pay_auth_p)时必传,在签约其他产品时无需传入。 周期扣款产品,会按照这里传入的参数提示用户,并对发起扣款的时间、金额、次数等做相应限制。
single_amount必选price(32)
【描述】单次扣款最大金额single_amount是周期扣款产品必填,即每次发起扣款时限制的最大金额,单位为元。商户每次发起扣款都不允许大于此金额。
【示例值】10.99
period_type可选string(10000)
【描述】周期类型period_type是周期扣款产品必填,枚举值为day和month。 day即扣款周期按天计,month代表扣款周期按自然月。 与另一参数period组合使用确定扣款周期,例如period_type为day,period=30,则扣款周期为30天;period_type为month,period=3,则扣款周期为3个自然月。 自然月是指,不论这个月有多少天,周期都计算到月份中的同一日期。例如1月3日到2月3日为一个自然月,1月3日到4月3日为三个自然月。注意周期类型使用month的时候,计划扣款时间execute_time不允许传28日之后的日期(可以传28日),以此避免有些月份可能不存在对应日期的情况。
【枚举值】
自然日: day
自然月: month
【示例值】day
period可选number(32)
【描述】周期数period是周期扣款产品必填。与另一参数period_type组合使用确定扣款周期,例如period_type为day,period=90,则扣款周期为90天。
【示例值】3
execute_time可选string(10000)
【描述】首次执行时间execute_time是周期扣款产品必填,即商户发起首次扣款的时间。精确到日,格式为yyyy-mm-dd 结合其他必填的扣款周期参数,会确定商户以后的扣款计划。发起扣款的时间需符合这里的扣款计划。
【示例值】2019-01-23
total_amount可选price(16)
【描述】总金额限制,单位为元。如果传入此参数,商户多次扣款的累计金额不允许超过此金额。
【示例值】600.00
total_payments可选number(8)
【描述】总扣款次数。如果传入此参数,则商户成功扣款的次数不能超过此次数限制(扣款失败不计入)。
【示例值】12
scene_rule_params|场景化规则可选sceneruleparams
【描述】周期扣中场景化规则信息,例如影音会员续费、保险等场景特殊规则字段
discount_period|优惠周期可选string(1000)
【描述】在周期扣场景化模板中配置优惠类型为优惠期玩法时需要该参数,表示后续有多少期扣款可享受优惠,值为自然数代表周期
【示例值】1
low_price_period|低价时长可选string(1000)
【描述】在周期扣场景化模板中配置优惠类型为低价玩法时需要该参数,表示代扣低价期持续的时间。单位是天,该值为自然数
【示例值】2
product_code可选string(64)
【描述】销售产品码,商户签约的支付宝合同所对应的产品码。
【示例值】general_withholding
external_logon_id可选string(100)
【描述】用户在商户网站的登录账号,用于在签约页面展示,如果为空,则不展示
【示例值】13852852877
sign_scene可选string(64)
【描述】协议签约场景,商户可根据 代扣产品常见场景值 选择符合自身的行业场景。 说明:当传入商户签约号 external_agreement_no 时,本参数必填,不能为默认值 default|default。
【示例值】industry|carrental
external_agreement_no可选string(32)
【描述】商户签约号,代扣协议中标示用户的唯一签约号(确保在商户系统中唯一)。 格式规则:支持大写小写字母和数字,最长32位。 商户系统按需自定义传入,如果同一用户在同一产品码、同一签约场景下,签订了多份代扣协议,那么需要指定并传入该值。
【示例值】test
third_party_type可选string(32)
【描述】签约第三方主体类型。对于三方协议,表示当前用户和哪一类的第三方主体进行签约。 默认为partner。
【枚举值】
平台商户: partner
【示例值】partner
sign_validity_period可选string(8)
【描述】当前用户签约请求的协议有效周期。 整形数字加上时间单位的协议有效期,从发起签约请求的时间开始算起。 目前支持的时间单位: 1. d:天 2. m:月 如果未传入,默认为长期有效。
【示例值】2m
zm_auth_params可选zmauthparams
【描述】芝麻授权信息,针对于信用代扣签约。json格式。
buckle_merchant_id必选string(64)
【描述】商户在芝麻端申请的merchantid
【示例值】268820000000414397785
buckle_app_id可选string(64)
【描述】商户在芝麻端申请的appid
【示例值】1001164
prod_params可选prodparams
【描述】签约产品属性,json格式
auth_biz_params可选string(256)
【描述】预授权业务信息
【示例值】{"platform":"taobao"}
pre_consult_id|前置收银咨询id可选string(1000)
【描述】前置收银id,商户接入前置收银台咨询时生成
【示例值】23954234125612
pay_operation_info|前置营销内容可选string(10000)
【描述】前置营销信息,由商户接入前置收银台后生成,在拉起独立签约时传递
【示例值】{\\\"payoperationid\\\":\\\"20240717192716a02065e6000ynn4482\\\",\\\"head_node_scenecode\\\":\\\"shopminiappprealipaycommon\\\",\\\"head_node_itemid\\\":\\\"24071212104015\\\"}
promo_params可选string(512)
【描述】签约营销参数,此值为json格式;具体的key需与营销约定
【示例值】{"key":"value"}
sub_merchant可选submerchantparams
【描述】此参数用于传递子商户信息,无特殊需求时不用关注。目前商户代扣、海外代扣、淘旅行信用住产品支持传入该参数(在销售方案中“是否允许自定义子商户信息”需要选是)。
sub_merchant_id可选string(30)
【描述】子商户的商户id
【示例值】2088123412341234
sub_merchant_name可选string(50)
【描述】子商户的商户名称
【示例值】滴滴出行
sub_merchant_service_name可选string(50)
【描述】子商户的服务名称
【示例值】滴滴出行免密支付
sub_merchant_service_description可选string(150)
【描述】子商户的服务描述
【示例值】免密付车费,单次最高500
device_params可选deviceparams
【描述】设备信息参数,在使用设备维度签约代扣协议时,可以传这些信息
device_id可选string(256)
【描述】设备id
【示例值】device12345
device_name可选string(128)
【描述】设备名称
【示例值】电视
device_type可选string(128)
【描述】设备类型
【枚举值】
vr一体机: vr_machine
电视: tv
身份证: id_card
【示例值】tv
identity_params可选identityparams
【描述】用户实名信息参数,包含:姓名、身份证号、签约指定uid。商户传入用户实名信息参数,支付宝会对比用户在支付宝端的实名信息。
以下参数 可选 传入
sign_user_idstring(32)
【描述】签约指定用户的uid,如用户登录的uid和指定的用户uid不一致则报错
新商户建议使用sign_open_id替代该字段。对于新商户,sign_user_id字段未来计划逐步回收,存量商户可继续使用。如使用sign_open_id,请确认 应用-开发配置-openid配置管理 已启用。无该配置项,可查看openid配置申请
【示例值】2088202888530893
sign_open_idstring(128)
【描述】签约指定用户的openid  详情可查看 openid简介
【示例值】031_dffvt0ufzk1852blpnhuswiztu4nqbko35ylxpow-y6
user_name可选string(64)
【描述】用户姓名
【示例值】张三
cert_no可选string(64)
【描述】用户身份证号
【示例值】61102619921108888
identity_hash可选string(128)
【描述】用户实名信息hash值
【示例值】8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92
agreement_effect_type可选string(30)
【描述】协议生效类型, 用于指定协议是立即生效还是等待商户通知再生效. 可空, 不填默认为立即生效.
【枚举值】
立即生效: direct
商户通知生效, 需要再次调用alipay.user.agreement.sign.effect (支付宝个人协议签约生效接口)接口推进协议生效.: notice
允许变更状态: allow_inactivate
【示例值】direct
user_age_range可选string(40)
【描述】商户希望限制的签约用户的年龄范围,min表示可签该协议的用户年龄下限,max表示年龄上限。如{"min": "18","max": "30"}表示18=<年龄<=30的用户可以签约该协议。
【示例值】{"min":"18","max":"30"}
effect_time可选number(86400)
【描述】签约有效时间限制,单位是秒,有效范围是0-86400,商户传入此字段会用商户传入的值否则使用支付宝侧默认值,在有效时间外进行签约,会进行安全拦截;(备注:此字段适用于需要开通安全防控的商户,且依赖商户传入生成签约时的时间戳字段timestamp)
【示例值】300
常见请求示例
package com.java.sdk.demo;
import com.alipay.api.alipayapiexception;
import com.alipay.api.alipayclient;
import com.alipay.api.defaultalipayclient;
import com.alipay.api.alipayconfig;
import com.alipay.api.domain.periodruleparams;
import com.alipay.api.domain.alipayuseragreementpagesignmodel;
import com.alipay.api.domain.identityparams;
import com.alipay.api.domain.accessparams;
import com.alipay.api.domain.zmauthparams;
import com.alipay.api.request.alipayuseragreementpagesignrequest;
import com.alipay.api.domain.prodparams;
import com.alipay.api.response.alipayuseragreementpagesignresponse;
import com.alipay.api.domain.deviceparams;
import com.alipay.api.domain.sceneruleparams;
import com.alipay.api.domain.submerchantparams;
import com.alipay.api.fileitem;
import java.util.base64;
import java.util.arraylist;
import java.util.list;
public class alipayuseragreementpagesign {
    public static void main(string[] args) throws alipayapiexception {
        // 初始化sdk
        alipayclient alipayclient = new defaultalipayclient(getalipayconfig());
        // 构造请求参数以调用接口
        alipayuseragreementpagesignrequest request = new alipayuseragreementpagesignrequest();
        alipayuseragreementpagesignmodel model = new alipayuseragreementpagesignmodel();
        
        // 设置销售产品码
        model.setproductcode("general_withholding");
        
        // 设置用户在商户网站的登录账号
        model.setexternallogonid("13852852877");
        
        // 设置个人签约产品码
        model.setpersonalproductcode("general_withholding_p");
        
        // 设置协议签约场景
        model.setsignscene("industry|carrental");
        
        // 设置商户签约号
        model.setexternalagreementno("test");
        
        // 设置签约第三方主体类型
        model.setthirdpartytype("partner");
        
        // 设置当前用户签约请求的协议有效周期
        model.setsignvalidityperiod("2m");
        
        // 设置芝麻授权信息
        zmauthparams zmauthparams = new zmauthparams();
        zmauthparams.setbuckleappid("1001164");
        zmauthparams.setbucklemerchantid("268820000000414397785");
        model.setzmauthparams(zmauthparams);
        
        // 设置签约产品属性
        prodparams prodparams = new prodparams();
        prodparams.setpayoperationinfo("{\\\"payoperationid\\\":\\\"20240717192716a02065e6000ynn4482\\\",\\\"head_node_scenecode\\\":\\\"shopminiappprealipaycommon\\\",\\\"head_node_itemid\\\":\\\"24071212104015\\\"}");
        prodparams.setauthbizparams("{\"platform\":\"taobao\"}");
        prodparams.setpreconsultid("23954234125612");
        model.setprodparams(prodparams);
        
        // 设置签约营销参数
        model.setpromoparams("{\"key\":\"value\"}");
        
        // 设置请按当前接入的方式进行填充
        accessparams accessparams = new accessparams();
        accessparams.setchannel("alipayapp");
        model.setaccessparams(accessparams);
        
        // 设置此参数用于传递子商户信息
        submerchantparams submerchant = new submerchantparams();
        submerchant.setsubmerchantname("滴滴出行");
        submerchant.setsubmerchantservicename("滴滴出行免密支付");
        submerchant.setsubmerchantservicedescription("免密付车费,单次最高500");
        submerchant.setsubmerchantid("2088123412341234");
        model.setsubmerchant(submerchant);
        
        // 设置设备信息参数
        deviceparams deviceparams = new deviceparams();
        deviceparams.setdevicename("电视");
        deviceparams.setdeviceid("device12345");
        deviceparams.setdevicetype("tv");
        model.setdeviceparams(deviceparams);
        
        // 设置用户实名信息参数
        identityparams identityparams = new identityparams();
        identityparams.setcertno("61102619921108888");
        // uid参数未来计划废弃,存量商户可继续使用,新商户请使用openid。请根据应用-开发配置-openid配置选择支持的字段。
        // identityparams.setsignuserid("2088202888530893");
        identityparams.setusername("张三");
        identityparams.setsignopenid("031_dffvt0ufzk1852blpnhuswiztu4nqbko35ylxpow-y6");
        identityparams.setidentityhash("8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92");
        model.setidentityparams(identityparams);
        
        // 设置协议生效类型
        model.setagreementeffecttype("direct");
        
        // 设置商户希望限制的签约用户的年龄范围
        model.setuseragerange("{\"min\":\"18\",\"max\":\"30\"}");
        
        // 设置周期管控规则参数period_rule_params
        periodruleparams periodruleparams = new periodruleparams();
        periodruleparams.setperiod(3l);
        periodruleparams.settotalamount("600.00");
        periodruleparams.setexecutetime("2019-01-23");
        periodruleparams.setsingleamount("10.99");
        periodruleparams.settotalpayments(12l);
        sceneruleparams sceneruleparams = new sceneruleparams();
        sceneruleparams.setdiscountperiod("1");
        sceneruleparams.setlowpriceperiod("2");
        periodruleparams.setsceneruleparams(sceneruleparams);
        periodruleparams.setperiodtype("day");
        model.setperiodruleparams(periodruleparams);
        
        // 设置签约有效时间限制
        model.seteffecttime(300l);
        
        request.setbizmodel(model);
        // 第三方代调用模式下请设置app_auth_token
        // request.putothertextparam("app_auth_token", "<-- 请填写应用授权令牌 -->");
        alipayuseragreementpagesignresponse response = alipayclient.pageexecute(request, "post");
        // 如果需要返回get请求,请使用
        // alipayuseragreementpagesignresponse response = alipayclient.pageexecute(request, "get");
        string pageredirectiondata = response.getbody();
        system.out.println(pageredirectiondata);
        if (response.issuccess()) {
            system.out.println("调用成功");
        } else {
            system.out.println("调用失败");
            // sdk版本是"4.38.0.all"及以上,可以参考下面的示例获取诊断链接
            // string diagnosisurl = diagnosisutils.getdiagnosis;
            // system.out.println(diagnosisurl);
        }
    }
    private static alipayconfig getalipayconfig() {
        string privatekey  = "<-- 请填写您的应用私钥,例如:miievqibadanb ... ... -->";
        string alipaypublickey = "<-- 请填写您的支付宝公钥,例如:miibijanbg... -->";
        alipayconfig alipayconfig = new alipayconfig();
        alipayconfig.setserverurl("https://openapi.alipay.com/gateway.do");
        alipayconfig.setappid("<-- 请填写您的appid,例如:2019091767145019 -->");
        alipayconfig.setprivatekey(privatekey);
        alipayconfig.setformat("json");
        alipayconfig.setalipaypublickey(alipaypublickey);
        alipayconfig.setcharset("utf-8");
        alipayconfig.setsigntype("rsa2");
        return alipayconfig;
    }
}
说明:本示例仅供参考。

公共响应参数

无公共响应参数

业务响应参数

pageredirectiondata|跳转页面数据必选string(16384)
【描述】用于跳转支付宝页面的信息,post和get方法生成内容不同:使用post方法执行,结果为html form表单,在浏览器渲染即可;使用get方法会得到支付宝url,需要打开或重定向到该url。建议使用post方式。具体使用方法请参考 接入指南
【示例值】请参考响应示例
响应示例
"punchout_form" method="post" action="https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.user.agreement.page.sign&format=json&sign=eritjkeijkjhkkkkkkkhjereeeeeeeeeee&version=1.0&app_id=2017060101317939&sign_type=rsa2×tamp=2014-07-24 03:07:50"> "hidden" name="biz_content" value="{"access_params":"","period_rule_params":"","sign_validity_period":"2m","external_logon_id":"13852852877","third_party_type":"partner","zm_auth_params":"","external_agreement_no":"test","product_code":"general_withholding","sub_merchant":"","prod_params":"","identity_params":"","device_params":"","personal_product_code":"general_withholding_p","user_age_range":"{\"min\":\"18\",\"max\":\"30\"}","promo_params":"{\"key\":\"value\"}","agreement_effect_type":"direct","sign_scene":"industry|carrental","effect_time":"300"}"> "submit" value="立即支付" style="display:none" >
说明:本示例仅供参考。

公共错误码

业务错误码

无业务错误码

触发通知示例

https://www.merchant.com/receive_notify.htm?notify_id=91722adff935e8cfa58b3aabf4dead6ibe¬ify_time=2017-02-16 21:46:15&sign_type=rsa2&sign=wco t3d8kg71dtlkwn7r9pzuoxeabjwp8/fousxcuskxsovyxbpsaidpryscjhcjmaglncjokjqlj28/asl93jotw39fx6i07lxhnbpknezalwmvpdnqui01hzszf9v1i6ggzjbiad5lg8bzttxzoj87ub2i9guj3nr/nuc9vey=&invalid_time=2017-05-20 11:49:19&sign_scene=industry|carrental&sign_time=2017-05-20 11:49:19&alipay_user_id=2088101143488930&status=normal&forex_eligible=t&external_logon_id=13852852877&app_id=2017060101317939&auth_app_id=2017060101317935&external_agreement_no=test&personal_product_code=general_withholding_p&valid_time=2017-05-20 11:49:19&agreement_no=20170502000610755993&zm_open_id=268816057852461313538942792&alipay_open_id=031_dffvt0ufzk1852blpnhuswiztu4nqbko35ylxpow-y6&merchant_app_id=2014072300007148&alipay_logon_id=test***ali@alipay.net¬ify_type=dut_user_sign&zm_score=700&single_quota=100&login_token=7ff7664d45c4afe8dccab8f224af9379_07&device_id=rsed235f875932&credit_auth_mode=deduct_huazhi&specified_sort_assets=[{"tail":"(8771)","bank_card_type":"dc"}]&partner_id=2088101143488930&modify_type=huazhi_degrade&next_deduct_time=2024-01-01
内容没有解决您的问题?您还可以前往 或 寻求帮助
凯发k8官方网娱乐官方 copyright © 支付宝(杭州)信息技术有限公司  | icp证浙b2-20160559
该文档对你是否有帮助?
当前页面目录
为开发者能享受更简单的协议处理逻辑、更丰富的开源工具配套、更低的接口响应时延,支付宝开放平台推出符合oas3.0规范的,助力开发体验。新版本文档请点击“查看v3版本”进行访问。
网站地图