alipay.user.agreement.page.sign(支付宝个人协议页面签约接口) 在线调试(沙箱环境)

支持用户在支付宝页面完成支付宝代扣协议的签约,目前只支付宝钱包H5页面场景。

公共参数

请求地址

环境HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 alipay.user.agreement.page.sign
format String 40 仅支持JSON JSON
return_url String 256 HTTP/HTTPS开头字符串 https://m.alipay.com/Gk8NF23
charset String 10 请求使用的编码格式,如utf-8,gbk,gb2312等 utf-8
sign_type String 10 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2
sign String 344 商户请求参数的签名串,详见签名 详见示例
timestamp String 19 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" 2014-07-24 03:07:50
version String 3 调用的接口版本,固定为:1.0 1.0
notify_url String 256 支付宝服务器主动通知商户服务器里指定的页面http/https路径。 http://api.test.alipay.net/atinterface/receive_notify.htm
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
sign_validity_period String 可选 8 当前用户签约请求的协议有效周期。
整形数字加上时间单位的协议有效期,从发起签约请求的时间开始算起。
目前支持的时间单位:
1. d:天
2. m:月
如果未传入,默认为长期有效。
2m
product_code String 可选 64 销售产品码,商户签约的支付宝合同所对应的产品码。 GENERAL_WITHHOLDING
external_logon_id String 可选 100 用户在商户网站的登录账号,用于在签约页面展示,如果为空,则不展示 13852852877
personal_product_code String 必选 64 个人签约产品码,商户和支付宝签约时确定,商户可咨询技术支持。 GENERAL_WITHHOLDING_P
sign_scene String 可选 64 协议签约场景,商户和支付宝签约时确定,商户可咨询技术支持。
当传入商户签约号external_agreement_no时,场景不能为默认值DEFAULT|DEFAULT。
INDUSTRY|CARRENTAL
external_agreement_no String 可选 32 商户签约号,代扣协议中标示用户的唯一签约号(确保在商户系统中唯一)。
格式规则:支持大写小写字母和数字,最长32位。
商户系统按需传入,如果同一用户在同一产品码、同一签约场景下,签订了多份代扣协议,那么需要指定并传入该值。
test
third_party_type String 可选 32 签约第三方主体类型。对于三方协议,表示当前用户和哪一类的第三方主体进行签约。
取值范围:
1. PARTNER(平台商户)
2. MERCHANT(集团商户),集团下子商户可共享用户签约内容
默认为PARTNER。
PARTNER
zm_auth_params ZmAuthParams 可选 芝麻授权信息,针对于信用代扣签约。json格式。
buckle_app_id String 可选 64 商户在芝麻端申请的appId 1001164
buckle_merchant_id String 必填 64 商户在芝麻端申请的merchantId 268820000000414397785
prod_params ProdParams 可选 签约产品属性,json格式
auth_biz_params String 可选 256 预授权业务信息 {"platform":"taobao"}
promo_params String 可选 512 签约营销参数,此值为json格式;具体的key需与营销约定 {"key":"value"}
access_params AccessParams 可选 请按当前接入的方式进行填充,且输入值必须为文档中的参数取值范围。
扫码或者短信页面签约需要拼装http的请求地址访问中间页面,钱包h5页面签约可直接拼接schema的请求地址
channel String 必填 20 目前支持以下值:
1. ALIPAYAPP (钱包h5页面签约)
2. QRCODE(扫码签约)
3. QRCODEORSMS(扫码签约或者短信签约)
ALIPAYAPP
sub_merchant SubMerchantParams 可选 此参数用于传递子商户信息,无特殊需求时不用关注。目前商户代扣、海外代扣、淘旅行信用住产品支持传入该参数(在销售方案中“是否允许自定义子商户信息”需要选是)。
sub_merchant_id String 可选 20 子商户的商户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、工牌:WORK_CARD
TV
merchant_process_url String 可选 1000 参数名:跳转商户处理url
应用场景:商户需要在签约流程中跳转到商户自己的页面做处理的场景,如获得用户授权获取实名信息等
如何获取:商户自己提供的页面地址
特殊说明:商户如果传递此参数,则会在签约流程中跳转所传递的地址,不传则不会跳转
https://www.merchantpage.com/index?processId=2345678
identity_params IdentityParams 可选 用户实名信息参数,包含:姓名、身份证号、签约指定uid。商户传入用户实名信息参数,支付宝会对比用户在支付宝端的实名信息。
user_name String 可选 64 用户姓名 张三
cert_no String 可选 64 用户身份证号 61102619921108888
identity_hash String 可选 128 用户实名信息hash值 8D969EEF6ECAD3C29A3A629280E686CF0C3F5D5A86AFF3CA12020C923ADC6C92
sign_user_id String 可选 32 签约指定用户的uid,如用户登录的uid和指定的用户uid不一致则报错 2088202888530893
agreement_effect_type String 可选 30 协议生效类型, 用于指定协议是立即生效还是等待商户通知再生效. 可空, 不填默认为立即生效.
DIRECT: 立即生效.
NOTICE: 商户通知生效, 需要再次调用alipay.user.agreement.sign.effect (支付宝个人协议签约生效接口)接口推进协议生效.
默认为DIRECT
DIRECT
user_age_range String 可选 40 商户希望限制的签约用户的年龄范围,min表示可签该协议的用户年龄下限,max表示年龄上限。如{"min": "18","max": "30"}表示18=<年龄<=30的用户可以签约该协议。 {"min":"18","max":"30"}
period_rule_params PeriodRuleParams 特殊可选 周期管控规则参数period_rule_params,在签约周期扣款产品(如CYCLE_PAY_AUTH_P)时必传,在签约其他产品时无需传入。 周期扣款产品,会按照这里传入的参数提示用户,并对发起扣款的时间、金额、次数等做相应限制。
period_type String 必填 20 周期类型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
period Number 必填 8 周期数period是周期扣款产品必填。与另一参数period_type组合使用确定扣款周期,例如period_type为DAY,period=90,则扣款周期为90天。 3
execute_time String 必填 16 首次执行时间execute_time是周期扣款产品必填,即商户发起首次扣款的时间。精确到日,格式为yyyy-MM-dd
结合其他必填的扣款周期参数,会确定商户以后的扣款计划。发起扣款的时间需符合这里的扣款计划。
2019-01-23
single_amount Price 必填 32 单次扣款最大金额single_amount是周期扣款产品必填,即每次发起扣款时限制的最大金额,单位为元。商户每次发起扣款都不允许大于此金额。 10.99
total_amount Price 可选 32 总金额限制,单位为元。如果传入此参数,商户多次扣款的累计金额不允许超过此金额。 600
total_payments Number 可选 8 总扣款次数。如果传入此参数,则商户成功扣款的次数不能超过此次数限制(扣款失败不计入)。 12
allow_huazhi_degrade String 可选 10 是否允许花芝GO降级成原代扣(即销售方案指定的代扣产品),在花芝GO场景下才会使用该值。取值:true-允许降级,false-不允许降级。默认为false。 false

响应参数

参数 类型 是否必填 最大长度 描述 示例值
external_agreement_no String 选填 32 代扣协议中标示用户的唯一签约号(确保在商户系统中唯一)。 test
personal_product_code String 必填 64 协议产品码,商户和支付宝签约时确定,不同业务场景对应不同的签约产品码。 GENERAL_WITHHOLDING_P
valid_time String 必填 32 用户代扣协议的实际生效时间,格式为yyyy-MM-dd HH:mm:ss。(只有签约成功才会返回) 2017-05-20 11:49:19
sign_scene String 必填 64 当前签约的协议场景。 INDUSTRY|CARRENTAL
agreement_no String 必填 64 支付宝系统中用以唯一标识用户签约记录的编号。(只有签约成功时才会返回) 20170502000610755993
zm_open_id String 选填 64 用户的芝麻信用openId,供商户查询用户芝麻信用使用。(只有签约成功时才返回) 268816057852461313538942792
invalid_time String 必填 32 用户代扣协议的失效时间,格式为yyyy-MM-dd HH:mm:ss。(只有签约成功才会返回) 2017-05-20 11:49:19
sign_time String 必填 32 支付宝代扣协议的实际签约时间,格式为yyyy-MM-dd HH:mm:ss。(只有签约成功才会返回) 2017-05-20 11:49:19
alipay_user_id String 必填 32 用户签约的支付宝账号对应的支付宝唯一用户号。
以2088开头的16位纯数字组成。(只有签约成功时才会返回)
2088101143488930
status String 必填 10 协议的当前状态。
1. TEMP:暂存,协议未生效过;
2. NORMAL:正常;
3. STOP:暂停。
(只有签约成功才会返回)
NORMAL
forex_eligible String 选填 10 是否海外购汇身份。值:T/F(只有在签约成功时才会返回) T
external_logon_id String 选填 100 用户在商户网站的登录账号,如果商户接口中未传,则不会返回 13852852877
alipay_logon_id String 必填 100 返回脱敏的支付宝账号,如需要返回不脱敏的支付宝用户账号,需要用户在签约页面上授权 test***ali@alipay.net
credit_auth_mode String 选填 64 授信模式,取值:DEDUCT_HUAZHI-花芝GO。 DEDUCT_HUAZHI

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayUserAgreementPageSignRequest request = new AlipayUserAgreementPageSignRequest();
request.setBizContent("{" +
"\"sign_validity_period\":\"2m\"," +
"\"product_code\":\"GENERAL_WITHHOLDING\"," +
"\"external_logon_id\":\"13852852877\"," +
"\"personal_product_code\":\"GENERAL_WITHHOLDING_P\"," +
"\"sign_scene\":\"INDUSTRY|CARRENTAL\"," +
"\"external_agreement_no\":\"test\"," +
"\"third_party_type\":\"PARTNER\"," +
"\"zm_auth_params\":{" +
"\"buckle_app_id\":\"1001164\"," +
"\"buckle_merchant_id\":\"268820000000414397785\"" +
"    }," +
"\"prod_params\":{" +
"\"auth_biz_params\":\"{\\\"platform\\\":\\\"taobao\\\"}\"" +
"    }," +
"\"promo_params\":\"{\\\"key\\\":\\\"value\\\"}\"," +
"\"access_params\":{" +
"\"channel\":\"ALIPAYAPP\"" +
"    }," +
"\"sub_merchant\":{" +
"\"sub_merchant_id\":\"2088123412341234\"," +
"\"sub_merchant_name\":\"滴滴出行\"," +
"\"sub_merchant_service_name\":\"滴滴出行免密支付\"," +
"\"sub_merchant_service_description\":\"免密付车费,单次最高500\"" +
"    }," +
"\"device_params\":{" +
"\"device_id\":\"device12345\"," +
"\"device_name\":\"电视\"," +
"\"device_type\":\"TV\"" +
"    }," +
"\"merchant_process_url\":\"https://www.merchantpage.com/index?processId=2345678\"," +
"\"identity_params\":{" +
"\"user_name\":\"张三\"," +
"\"cert_no\":\"61102619921108888\"," +
"\"identity_hash\":\"8D969EEF6ECAD3C29A3A629280E686CF0C3F5D5A86AFF3CA12020C923ADC6C92\"," +
"\"sign_user_id\":\"2088202888530893\"" +
"    }," +
"\"agreement_effect_type\":\"DIRECT\"," +
"\"user_age_range\":\"{\\\"min\\\":\\\"18\\\",\\\"max\\\":\\\"30\\\"}\"," +
"\"period_rule_params\":{" +
"\"period_type\":\"DAY\"," +
"\"period\":3," +
"\"execute_time\":\"2019-01-23\"," +
"\"single_amount\":10.99," +
"\"total_amount\":600," +
"\"total_payments\":12" +
"    }," +
"\"allow_huazhi_degrade\":\"false\"" +
"  }");
AlipayUserAgreementPageSignResponse response = alipayClient.pageExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "alipay_user_agreement_page_sign_response": {
        "code": "10000",
        "msg": "Success",
        "external_agreement_no": "test",
        "personal_product_code": "GENERAL_WITHHOLDING_P",
        "valid_time": "2017-05-20 11:49:19",
        "sign_scene": "INDUSTRY|CARRENTAL",
        "agreement_no": "20170502000610755993",
        "zm_open_id": "268816057852461313538942792",
        "invalid_time": "2017-05-20 11:49:19",
        "sign_time": "2017-05-20 11:49:19",
        "alipay_user_id": "2088101143488930",
        "status": "NORMAL",
        "forex_eligible": "T",
        "external_logon_id": "13852852877",
        "alipay_logon_id": "test***ali@alipay.net",
        "credit_auth_mode": "DEDUCT_HUAZHI"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

{
    "alipay_user_agreement_page_sign_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "系统繁忙"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

业务错误码

公共错误码

错误码错误描述解决方案
ERROR_RISK_ACCOUNT_FROZEN 用户账户被冻结 提示用户解冻支付宝账号
ERROR_RISK_BLANCE_PAY_CLOSE 用户账号余额支付功能关闭 提示用户支付宝账号打开余额支付功能
USER_ACCOUNT_NOT_BINDED_MOBILE 用户账户未绑定手机 提示用户支付宝账号绑定手机号
MERCHANT_AGREEMENT_IS_NOT_EXIST 商户协议不存在 商户与支付宝签约代扣合同
PRODUCT_CODE_NOT_SUPPORTED_ERROR 无效的个人产品码 商户确认个人产品码填写是否正确
USER_AGREEMENT_PERIOD_CONFILICT 协议已存在,协议有效周期冲突 接口填入的协议有效期与已签约的协议有效期冲突,需填入已存协议的有效期
USER_REALNAME_STAUTS_ERROR 用户未实名不允许签约 提示用户补充支付宝账号信息完成实名制
ACCOUNT_LEVEL_CHECK_FAIL 用户账户等级不满足签约要求 提示用户在支付宝主站提高个人支付宝账户等级
ZHIMA_SCORE_VALIDATE_FAILED 用户芝麻分校验失败 信用代扣场景,用户芝麻分不满足商户设定的签约芝麻分
ZHIMA_AUTHORIZE_FAILED 芝麻授权开通失败 信用代扣场景,授权开通芝麻失败,需与芝麻共同排查原因
ZHIMA_RISK_VALIDATE_FAILED 芝麻风险名单校验失败 信用代扣场景,用户支付宝账号未通过芝麻风险名单校验
USER_INFO_NOT_MATCH 外部签约号已签约场景,用户信息不匹配 商户更改外部签约号
MERCHANT_STATUS_IS_NOT_NORMAL 商户协议状态不正常 商户确认与支付宝的签约合同是否已失效,并重新签约商户合同
MERCHANT_AGREEMENT_OUT_OF_DATE 商户协议已过期 商户确认与支付宝的合同的有效期是否已过期,并重新签约商户合同
MAX_SIGN_COUNT_CHECK_FAIL 用户最大签约次数检查失败 用户在该商户下已签约的协议数达到商户允许的最大签约协议数量,无法继续签约
INVALID_PARAMETER 参数有误 参数错误,请确认传参是否正确
SYSTEM_ERROR 系统繁忙 系统繁忙,需排查具体原因
USER_NOT_ALLOW_FOREX_ELIGIBLE 用户不具备海外购汇身份信息 需用户补全海外购汇身份信息
BUSINESS_NOT_SUPPORTED_ERROR 不支持的业务 商户确认传入业务参数是否符合业务要求
USER_MOBILE_NOT_MATCH_ERROR 用户手机号不匹配 商户传入的手机号与用户支付宝绑定的手机号不一致
ERROR_RIST_CTU_REFUSE 操作存在风险,被CTU拒绝 确认用户的具体操作风险
USER_NOT_EXIST_ERROR 用户信息不存在 无法查到用户信息,确认用户信息是否存在
USER_ACCOUNT_NOT_EXIST 用户账户信息不存在 无法查到用户账户信息,确认用户账户信息是否存在
SECURITY_CHECK_FAIL 操作存在风险 签约操作存在风险,需与支付宝确认具体被拦截原因
VALIDATECODE_EXPIRED 校验码超时 校验码超时,请重新获取
SIGN_USER_ID_NOT_MATCH 签约账号不匹配 用户根据错误页面上提示的支付宝账号重新登录签约
USER_AGE_RANGE_NOT_MATCH 不在商户业务允许的年龄范围 提示用户的年龄不在商户业务允许的年龄范围,无法继续签约

触发通知示例

https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync&notify_id=91722adff935e8cfa58b3aabf4dead6ibe&notify_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_logon_id=test***ali@alipay.net&notify_type=dut_user_sign&zm_score=700&login_token=7ff7664d45c4afe8dccab8f224af9379_07&device_id=RSED235F875932&credit_auth_mode=DEDUCT_HUAZHI
onlineServer