淘宝开放平台

登录
文档中心 > API类目 > 会员API

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 String 可选 1000 此参数用于传递子商户信息，目前商户代扣、海外代扣、淘旅行信用住产品支持传入该参数(销售方案中是否允许自定义子商户信息选是)；
目前支持四个key值：
sub_merchant_id (子商户id)
sub_merchant_name (子商户名称)
sub_merchant_service_name (子商户服务名称)
sub_merchant_service_description (子商户服务描述)		 {"sub_merchant_name":"子商户名称","sub_merchant_service_name":"子商户服务名称","sub_merchant_service_description":"子商户服务描述"}
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
  • └ device_display
  • String
  • 必填
  • 128
  • 设备的展示文案
  • XiaoMi_VR
  • └ device_apdid_token
  • String
  • 必填
  • 128
  • 设备的apdidToken
  • 9a4790232a456b4e71c130d03780233e22ce15f2a7c7208ea75f89d97f69f5bb
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

公共响应参数

参数 类型 是否必填 最大长度 描述 示例值
code String 是 - 网关返回码,详见文档 40004
msg String 是 - 网关返回码描述,详见文档 Business Failed
sub_code String 否 - 业务返回码,详见文档 ACQ.TRADE_HAS_SUCCESS
sub_msg String 否 - 业务返回码描述,详见文档 交易已被支付
sign String 是 - 签名,详见文档 DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=

响应参数

参数 类型 是否必填 最大长度 描述 示例值
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

请求示例

  • JAVA
  • .NET
  • PHP
  • HTTP请求源码
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_name\\\":\\\"子商户名称\\\",\\\"sub_merchant_service_name\\\":\\\"子商户服务名称\\\",\\\"sub_merchant_service_description\\\":\\\"子商户服务描述\\\"}\"," +
"\"device_params\":{" +
"\"device_id\":\"device12345\"," +
"\"device_name\":\"电视\"," +
"\"device_type\":\"TV\"," +
"\"device_display\":\"XiaoMi_VR\"," +
"\"device_apdid_token\":\"9a4790232a456b4e71c130d03780233e22ce15f2a7c7208ea75f89d97f69f5bb\"" +
"    }," +
"\"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\"" +
"  }");
AlipayUserAgreementPageSignResponse response = alipayClient.pageExecute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

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

异常示例

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

业务错误码

错误码 错误描述 解决方案
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 签约账号不匹配 用户根据错误页面上提示的支付宝账号重新登录签约

公共错误码

公共错误码

触发通知字段

参数 类型 是否必填 最大长度 描述 示例值
app_id String 必填 64 支付宝分配给开发者的应用Id 2017060101317939
auth_app_id String 必填 64 支付宝分配给商户的应用Id 2017060101317935
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
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_scene String 必填 64 当前签约的协议场景。 INDUSTRY|CARRENTAL
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
notify_type String 必填 100 用户签约成功通知类型 dut_user_sign
zm_score String 选填 20 用户支付宝芝麻分 700
login_token String 选填 1000 用户登录token，目前用于集团的信任登录 7ff7664d45c4afe8dccab8f224af9379_07
device_id String 选填 256 设备Id RSED235F875932

触发通知示例

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=&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&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&alipay_logon_id=test***ali@alipay.net&notify_type=dut_user_sign&zm_score=700&login_token=7ff7664d45c4afe8dccab8f224af9379_07&device_id=RSED235F875932

异步通知验签方式

异步通知验签方式
有用(0)
我要提问
返回
顶部