通用场景
支付宝个人代扣协议查询接口
公共请求参数
业务请求参数
以下参数 可选 传入
alipay_user_idstring(32)
【描述】用户的支付宝账号对应 的支付宝唯一用户号，以 2088 开头的 16 位纯数字 组成。
本参数与alipay_logon_id若都填写，则以本参数为准，优先级高于 alipay_logon_id。
新商户建议使用alipay_open_id替代该字段。对于新商户，alipay_user_id字段未来计划逐步回收，存量商户可继续使用。如使用alipay_open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。
【示例值】2088101122675263
alipay_open_idstring(128)
【描述】用户的支付宝账号对应 的支付宝唯一用户号，
本参数与alipay_logon_id若都填写，则以本参数为准，优先级高于 alipay_logon_id。 详情可查看 openid简介
【示例值】074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5
personal_product_code可选string(64)
【描述】协议产品码，商户和支付宝签约时确定，商户可咨询凯发app官方网站的技术支持。
【示例值】general_withholding_p
alipay_logon_id可选string(100)
【描述】用户的支付宝登录账号，支持邮箱或手机号码格式。本参数与alipay_open_id 或 alipay_user_id 同时填写，优先按照 alipay_open_id 或 alipay_user_id 处理。
【示例值】abx@alitest.com
sign_scene可选string(64)
【描述】签约场景码，该值需要与系统/页面签约接口调用时传入的值保持一 致。如：周期扣款场景与调用 alipay.user.agreement.page.sign(支付宝个人协议页面签约接口) 签约时的 sign_scene 相同。
注意：当传入商户签约号 external_agreement_no 时，该值不能为空或默认值 default|default。
【示例值】industry|medical
external_agreement_no可选string(32)
【描述】代扣协议中标示用户的唯一签约号(确保在商户系统中
唯一)。
格式规则:支持大写小写字母和数字，最长 32 位。
【示例值】test
third_party_type可选string(32)
【描述】签约第三方主体类型。对于三方协议，表示当前用户和哪一类的第三方主体进行签约。
默认为partner。
【枚举值】
平台商户: partner
【示例值】partner
agreement_no可选string(64)
【描述】支付宝系统中用以唯一标识用户签约记录的编号（用户签约成功后的协议号 ） ，如果传了该参数，其他参数会被忽略
【示例值】20170322450983769228
常见请求示例
默认示例
curl 'https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.user.agreement.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=rsa2×tamp=${now}' \
-f 'app_auth_token=${app_auth_token}' \
-f 'biz_content={
"personal_product_code":"general_withholding_p",
"alipay_user_id":"2088101122675263",
"alipay_open_id":"074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5",
"alipay_logon_id":"abx@alitest.com",
"sign_scene":"industry|medical",
"external_agreement_no":"test",
"third_party_type":"partner",
"agreement_no":"20170322450983769228"
}' 说明：本示例仅供参考。
公共响应参数
业务响应参数
valid_time必选string(32)
【描述】协议生效时间，格式为 yyyy-mm-dd hh:mm:ss。
【示例值】2017-05-24 15:00:40
alipay_logon_id必选string(100)
【描述】返回脱敏的支付宝账号
【示例值】test***ali@alipay.net
invalid_time必选string(32)
【描述】协议失效时间，格式为 yyyy-mm-dd hh:mm:ss。
【示例值】2117-05-24 00:00:00
pricipal_type必选string(10)
【描述】签约主体类型。
【枚举值】
支付宝账号: card
【示例值】card
sign_scene必选string(64)
【描述】签约协议的场景。
【示例值】industry|carrental
agreement_no必选string(64)
【描述】用户签约成功后的协议号
【示例值】20170322450983769228
third_party_type必选string(32)
【描述】签约第三方主体类型。对于三方协议，表示当前用户和哪一类的第三方主体进行签约。
默认为partner。
【枚举值】
平台商户: partner
【示例值】partner
status必选string(32)
【描述】协议当前状态
1. temp：暂存，协议未生效过；
2. normal：正常；
3. stop：暂停
【示例值】normal
sign_time必选string(32)
【描述】协议签约时间，格式为 yyyy-mm-dd hh:mm:ss。
【示例值】2017-05-24 15:00:40
personal_product_code必选string(64)
【描述】协议产品码，商户和支付宝签约时确定，不同业务场景对应不同的签约产品码。
【示例值】general_withholding_p
以下参数 二选一
principal_idstring(32)
【描述】签约主体标识。
当principal_type为card 时，该字段为支付宝用户号;
新商户建议使用principal_open_id替代该字段。对于新商户，principal_id字段未来计划逐步回收，存量商户可继续使用。如使用principal_open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。
【示例值】2088101122675263
principal_open_idstring(128)
【描述】签约主体标识。
当principal_type为card 时，该字段为支付宝用户号; 详情可查看 openid简介
【示例值】074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5
device_id特殊可选string(256)
【描述】设备id
【示例值】rsed235f875932
external_agreement_no特殊可选string(32)
【描述】代扣协议中标示用户的唯一签约号(确保在商户系统中唯一)。当入参中传了此参数时返回。
【示例值】test
zm_open_id特殊可选string(64)
【描述】用户的芝麻信用 openid，供商 户查询用户芝麻信用使用。
【示例值】268816057852461313538942792
external_logon_id特殊可选string(100)
【描述】外部登录id。当入参中传了此参数时返回。
【示例值】2088101118392209
credit_auth_mode特殊可选string(32)
【描述】授信模式，目前只在花芝代扣（即花芝go）协议时才会返回
【枚举值】
花芝go: deduct_huazhi
【示例值】deduct_huazhi
single_quota特殊可选string(10)
【描述】单笔代扣额度
【示例值】100.00
last_deduct_time可选string(20)
【描述】周期扣协议，上次扣款成功时间
【示例值】2022-05-15
next_deduct_time可选string(20)
【描述】周期扣协议，预计下次扣款时间
【示例值】2022-06-15
execution_plans｜还款计划列表可选executionplan[]
【描述】还款计划列表
single_amount｜单笔金额必选string(5000)
【描述】周期扣中单笔金额，单位是元
【示例值】100.00
period_id｜期数可选string(5000)
【描述】该值为自然数，表示周期扣期数。
【示例值】1
execute_time｜预期执行时间可选string(5000)
【描述】周期扣预期执行时间，格式为yyyy-mm-dd
【示例值】2024-04-29
latest_execute_time｜最晚执行时间可选string(5000)
【描述】周期扣执行计划最晚执行时间，格式为yyyy-mm-dd
【示例值】2024-05-30
响应示例
正常示例
异常示例
{
"alipay_user_agreement_query_response": {
"code": "10000",
"msg": "success",
"principal_id": "2088101122675263",
"principal_open_id": "074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5",
"valid_time": "2017-05-24 15:00:40",
"alipay_logon_id": "test***ali@alipay.net",
"invalid_time": "2117-05-24 00:00:00",
"pricipal_type": "card",
"device_id": "rsed235f875932",
"sign_scene": "industry|carrental",
"agreement_no": "20170322450983769228",
"third_party_type": "partner",
"status": "normal",
"sign_time": "2017-05-24 15:00:40",
"personal_product_code": "general_withholding_p",
"external_agreement_no": "test",
"zm_open_id": "268816057852461313538942792",
"external_logon_id": "2088101118392209",
"credit_auth_mode": "deduct_huazhi",
"single_quota": "100.00",
"last_deduct_time": "2022-05-15",
"next_deduct_time": "2022-06-15",
"execution_plans": [
{
"single_amount": "100.00",
"period_id": "1",
"execute_time": "2024-04-29",
"latest_execute_time": "2024-05-30"
}
]
},
"sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}说明：本示例仅供参考。
公共错误码
业务错误码
| 错误码 | 错误描述 | 凯发app官方网站的解决方案 |
|---|---|---|
| system_error | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常，导致服务调用失败，商户可以用同样的请求发起重试 |
| invalid_parameter | 参数有误 | 请根据接口返回的参数非法的具体错误信息，修改参数后进行重试 |
| agreement_has_unsigned | 用户协议已解约 | 用户于支付宝侧协议已解约，商户需解约对应协议 |
| authoree_is_not_match | 被授权方不匹配 | 确认商户app_id对应的被授权方与用户协议中的被授权方是否一致 |
| logonid_is_repeated | 登录账户名与他人重复 | 登录账户名与他人重复 |
| merchant_status_is_not_normal | 商户协议状态不正常 | 检查商户协议是否正确 |
| parent_merchant_query_fail | 平台商户查询失败 | 检查父商户是否存在，或重试处理 |
| product_code_not_supported_error | 无效的个人产品码 | 商户确认个人产品码填写是否正确 |
| user_agreement_not_exist | 用户协议不存在 | 检查用户协议是否正确 |
| user_not_exist_error | 支付宝用户信息不存在 | 检查用户信息是否正确 |
| user_not_exsit_error | 用户信息不存在 | 检查用户信息是否正确 |