接口说明
该接口是页面跳转接口,用于生成用户访问支付宝的跳转链接。请在服务端执行支付宝sdk中pageexecute方法,读取响应中的body()结果。该结果用于跳转到支付宝页面,返回到用户浏览器渲染或重定向跳转到支付宝页面。具体使用方法请参考
通用场景
支持用户在支付宝页面完成支付宝代扣协议的签约,目前只支持支付宝钱包h5页面场景。
公共请求参数
业务请求参数
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方式。具体使用方法请参考
【示例值】请参考响应示例
响应示例
正常示例
说明:本示例仅供参考。
公共错误码
业务错误码
无业务错误码
触发通知示例
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