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

alipay.user.agreement.sign (支付宝个人协议签约接口)

用户在商户平台上与支付宝签约三方代扣协议，如果选择PC校验码签约确认方式，则需要与alipay.user.agreement.sign.confirm接口配合使用，如果选择无需确认，则可直接完成协议签约；

公共参数

请求地址：
环境 HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do
公共请求参数：
参数 类型 是否必填 最大长度 描述 示例值
app_id String 是 32 支付宝分配给开发者的应用ID 2014072300007148
method String 是 128 接口名称 alipay.user.agreement.sign
format String 否 40 仅支持JSON JSON
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 是 - 请求参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递，具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
external_logon_id String 可选 100 用户在商户网站的登录账号，用于在签约页面展示，如果为空，则不展示 13852852877
alipay_user_id String 可选 32 用户的支付宝id，本参数与alipay_logon_id不可同时为空，若都填写，则以本参数为准，优先级高于alipay_logon_id。 2088102008779321
alipay_logon_id String 可选 100 用户的支付宝登录账号，支持邮箱或手机号码格式。
本参数与alipay_user_id不可同时为空，若都填写，则以alipay_user_id为准。		 zfb@alitest.com
personal_product_code String 必须 64 个人签约产品码，商户和支付宝签约时确定，商户可咨询技术支持。 GENERAL_WITHHOLDING_P
sign_scene String 可选 64 协议签约场景，商户和支付宝签约时确定，商户可咨询技术支持。
当传入商户签约号external_sign_no时，场景不能为默认值DEFAULT|DEFAULT。		 INDUSTRY|CARRENTAL
external_agreement_no String 可选 32 商户签约号，代扣协议中标示用户的唯一签约号（确保在商户系统中唯一）。
格式规则：支持大写小写字母和数字，最长32位。
商户系统按需传入，如果同一用户在同一产品码、同一签约场景下，签订了多份代扣协议，那么需要指定并传入该值。		 test
binded_mobile String 可选 20 支付宝账户绑定的手机，系统会对账户绑定的手机与传入的手机号做一致性校验。
商户调用必传。
阿里集团内部调用，可不传。		 13852852877
confirm_type String 可选 1 签约确认方式，用户进行协议签约时的确认方式，不同产品所支持的确认方式不同。
目前仅支持如下两类：
M：手机校验码回填确认方式。
如果为空，则默认为无需用户确认。		 M
third_party_type String 可选 32 签约第三方主体类型。对于三方协议，表示当前用户和哪一类的第三方主体进行签约。
取值范围：
1. PARTNER（平台商户）
2. MERCHANT（集团商户），集团下子商户可共享用户签约内容
默认为PARTNER。		 PARTNER
verify_params VerifyParams 可选 - 校验信息，针对双因子校验逻辑，如果logonId为email时，必须传入证件号后4位信息。Json格式。
  • └ cert_no
  • String
  • 必填
  • 64
  • 用户证件号后4位
  • 2135
sign_validity_period String 可选 8 当前用户签约请求的协议有效周期。
整形数字加上时间单位的协议有效期，从发起签约请求的时间开始算起。
目前支持的时间单位：
1. d：天
2. m：月
如果未传入，默认为长期有效。		 2m
prod_params ProdParams 可选 - 签约产品属性，json格式
  • └ auth_biz_params
  • String
  • 可选
  • 256
  • 预授权业务信息
  • {"platform":"taobao"}
product_code String 可选 64 销售产品码，商户签约的支付宝合同所对应的产品码。 GENERAL_WITHHOLDING
zm_auth_params ZmAuthParams 可选 - 芝麻授权信息，针对于信用代扣签约。json格式。
  • └ buckle_app_id
  • String
  • 可选
  • 64
  • 商户在芝麻端申请的appId
  • 1001164
  • └ buckle_merchant_id
  • String
  • 必填
  • 64
  • 商户在芝麻端申请的merchantId
  • 268820000000414397785
asset_params AssetParams 可选 - 资产信息，针对于泛金融机构，签约时必须传入资产信息。json格式。
  • └ asset_type
  • String
  • 必填
  • 10
  • 资产类型：
    1. BANK（银行卡）
    2. ACCOUNT（账号模式）
  • BANK
  • └ card_no
  • String
  • 必填
  • 64
  • 银行卡号。
    assetType为BANK时，必填。
  • 8888888275464798
  • └ inst_id
  • String
  • 必填
  • 64
  • 机构ID。
    assetType为BANK时，必填。
  • ANTBANK
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
promo_params String 可选 512 签约营销参数，此值为json格式；具体的key需与营销约定 {"key":"value"}
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":"子商户服务描述"}

公共响应参数

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

响应参数

参数 类型 是否必填 最大长度 描述 示例值
apply_token String 选填 64 签约申请token，其格式和内容，由支付宝定义。在需要签约确认的场景下，商户可根据申请操作成功时返回的申请token，进行后续的确认操作。
1. 不需要用户进行签约确认时，不返回本参数。
2. 需要用户进行签约确认时，本参数不为空。 		MDEDUCT0019e92ca377d1d44b65fa24ec9cd89132f
alipay_user_id String 必填 32 签约申请成功的场景下，会同步返回用户签约的支付宝账号对应的支付宝唯一用户id。
以2088开头的16位纯数字组成。 		2088101143488930
agreement_no String 选填 64 在无需用户确认且签约成功的场景下，会同步返回签约协议号。 20170502000610755993
forex_eligible String 选填 10 是否海外购汇身份 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");
AlipayUserAgreementSignRequest request = new AlipayUserAgreementSignRequest();
request.setBizContent("{" +
"\"external_logon_id\":\"13852852877\"," +
"\"alipay_user_id\":\"2088102008779321\"," +
"\"alipay_logon_id\":\"zfb@alitest.com\"," +
"\"personal_product_code\":\"GENERAL_WITHHOLDING_P\"," +
"\"sign_scene\":\"INDUSTRY|CARRENTAL\"," +
"\"external_agreement_no\":\"test\"," +
"\"binded_mobile\":\"13852852877\"," +
"\"confirm_type\":\"M\"," +
"\"third_party_type\":\"PARTNER\"," +
"\"verify_params\":{" +
"\"cert_no\":\"2135\"" +
"    }," +
"\"sign_validity_period\":\"2m\"," +
"\"prod_params\":{" +
"\"auth_biz_params\":\"{\\\"platform\\\":\\\"taobao\\\"}\"" +
"    }," +
"\"product_code\":\"GENERAL_WITHHOLDING\"," +
"\"zm_auth_params\":{" +
"\"buckle_app_id\":\"1001164\"," +
"\"buckle_merchant_id\":\"268820000000414397785\"" +
"    }," +
"\"asset_params\":{" +
"\"asset_type\":\"BANK\"," +
"\"card_no\":\"8888888275464798\"," +
"\"inst_id\":\"ANTBANK\"" +
"    }," +
"\"device_params\":{" +
"\"device_id\":\"device12345\"," +
"\"device_name\":\"电视\"," +
"\"device_type\":\"TV\"," +
"\"device_display\":\"XiaoMi_VR\"," +
"\"device_apdid_token\":\"9a4790232a456b4e71c130d03780233e22ce15f2a7c7208ea75f89d97f69f5bb\"" +
"    }," +
"\"promo_params\":\"{\\\"key\\\":\\\"value\\\"}\"," +
"\"sub_merchant\":\"{\\\"sub_merchant_name\\\":\\\"子商户名称\\\",\\\"sub_merchant_service_name\\\":\\\"子商户服务名称\\\",\\\"sub_merchant_service_description\\\":\\\"子商户服务描述\\\"}\"" +
"  }");
AlipayUserAgreementSignResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

  • JSON示例
{
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
	"alipay_user_agreement_sign_response":{
		"msg":"Success",
		"code":"10000",
		"apply_token":"MDEDUCT0019e92ca377d1d44b65fa24ec9cd89132f",
		"agreement_no":"20170502000610755993",
		"external_logon_id":"13852852877",
		"alipay_user_id":"2088101143488930",
		"forex_eligible":"T",
		"alipay_logon_id":"test***ali@alipay.net"
	}
}

异常示例

  • JSON示例
{
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
	"alipay_user_agreement_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_LIST_VALIDATE_FAILED 芝麻风险名单校验失败 信用代扣场景，用户支付宝账号未通过芝麻风险名单校验
USER_INFO_IS_NOT_MATCH 外部签约号已签约场景，用户信息不匹配 商户更改外部签约号
MERCHANT_STATUS_IS_NOT_NORMAL 商户协议状态不正常 商户确认与支付宝的签约合同是否已失效，并重新签约商户合同
MERCHANT_AGREEMENT_OUT_OF_DATE 商户协议已过期 商户确认与支付宝的合同的有效期是否已过期，并重新签约商户合同
REFUESD_BY_CTU 操作存在风险，被CTU拒绝 签约操作存在风险，被CTU拦截，需与支付宝确认具体被拦截原因
MAX_SIGN_COUNT_CHECK_FAIL 用户最大签约次数检查失败 用户在该商户下已签约的协议数达到商户允许的最大签约协议数量，无法继续签约
USER_NOT_ALLOW_FOREX_ELIGIBLE 用户不具备海外购汇身份信息 需用户补全海外购汇身份信息
INVALID_PARAMETER 参数有误 参数错误，请确认传参是否正确
SYSTEM_ERROR 系统繁忙 系统繁忙，需排查具体原因
BUSINESS_NOT_SUPPORTED_ERROR 不支持的业务 商户确认传入业务参数是否符合业务要求
USER_MOBILE_NOT_MATCH_ERROR 用户手机号不匹配 商户传入的手机号与用户支付宝绑定的手机号不一致
ERROR_RIST_CTU_REFUSE 操作存在风险，被CTU拒绝 确认用户的具体操作风险
USER_NOT_EXIST_ERROR 用户信息不存在 无法查到用户信息，确认用户信息是否存在
USER_ACCOUNT_NOT_EXIST 用户账户信息不存在 无法查到用户账户信息，确认用户账户信息是否存在
ACK_CODE_SEND_FAIL 用户短信校验码下发失败 确认用户账号绑定的手机号是否正常
USER_CERT_NO_IS_NOT_MATCH 用户证件号不匹配 用户证件号不匹配，请确认传送的证件号与用户信息是否正确
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
agreement_no String 必填 64 支付宝系统中用以唯一标识用户签约记录的编号。 20170502000610755993
zm_open_id String 选填 64 用户的芝麻信用openId，供商户查询用户芝麻信用使用。 268816057852461313538942792
valid_time String 必填 32 用户代扣协议的实际生效时间，格式为yyyy-MM-dd HH:mm:ss。 2017-05-20 11:49:19
invalid_time String 必填 32 用户代扣协议的失效时间，格式为yyyy-MM-dd HH:mm:ss。 2017-05-20 11:49:19
alipay_logon_id String 必填 100 返回脱敏的支付宝账号 test***ali@alipay.net
notify_type String 必填 100 用户签约成功通知类型 dut_user_sign
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
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&agreement_no=20170502000610755993&zm_open_id=268816057852461313538942792&valid_time=2017-05-20 11:49:19&invalid_time=2017-05-20 11:49:19&alipay_logon_id=test***ali@alipay.net&notify_type=dut_user_sign&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&device_id=RSED235F875932

异步通知验签方式

异步通知验签方式
有用(0)
我要提问
返回
顶部
阿里巴巴集团 | 淘宝网 | 天猫 | 聚划算 | 全球速卖通 | 阿里巴巴国际交易市场 | 1688 | 阿里妈妈 | 阿里旅行·去啊 | 阿里云计算 | YunOS | 阿里通信 | 万网 | 高德 | 优视 | 友盟 | 酷盘 | 虾米 | 天天动听 | 来往 | 钉钉 | 11Main | 支付宝
关于淘宝 合作伙伴 营销中心 联系客服 开放平台 诚征英才 联系我们 网站地图 法律声明 © 2016 Taobao.com 版权所有
网络文化经营许可证：文网文[2010]040号 | 增值电信业务经营许可证：浙B2-20080224-1 | 信息网络传播视听节目许可证：1109364号