alipay.user.agreement.transfer(协议由普通通用代扣协议产品转移到周期扣协议产品) 在线调试(沙箱环境)

由商户调用,将商户之前通用代扣产品转移到周期扣的协议产品

公共参数

请求地址

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

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 alipay.user.agreement.transfer
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
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
agreement_no String 必选 64 支付宝系统中用以唯一标识用户签约记录的编号(用户签约成功后的协议号 ),如果传了该参数,其他参数会被忽略 20170322450983769228
target_product_code String 必选 64 协议产品码,商户和支付宝签约时确定,不同业务场景对应不同的签约产品码。这里指的是需要修改目标产品码的值 CYCLE_PAY_AUTH_P
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

响应参数

参数 类型 是否必填 最大长度 描述 示例值
execute_time String 选填 1000 执行时间 2019-01-23
period_type String 选填 1000 周期类型 DAY
amount String 选填 1000 单次金额限制 100
total_amount String 选填 1000 总金额限制 600
total_payments String 选填 1000 总支付次数 12
period String 选填 1000 周期 7

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayUserAgreementTransferRequest request = new AlipayUserAgreementTransferRequest();
request.setBizContent("{" +
"\"agreement_no\":\"20170322450983769228\"," +
"\"target_product_code\":\"CYCLE_PAY_AUTH_P\"," +
"\"period_rule_params\":{" +
"\"period_type\":\"DAY\"," +
"\"period\":3," +
"\"execute_time\":\"2019-01-23\"," +
"\"single_amount\":10.99," +
"\"total_amount\":600," +
"\"total_payments\":12" +
"    }" +
"  }");
AlipayUserAgreementTransferResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "alipay_user_agreement_transfer_response": {
        "code": "10000",
        "msg": "Success",
        "execute_time": "2019-01-23",
        "period_type": "DAY",
        "amount": "100",
        "total_amount": "600",
        "total_payments": "12",
        "period": "7"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

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

业务错误码

公共错误码

错误码错误描述解决方案
USER_AGREEMENT_NOT_EXIST 用户协议不存在 确认用户是否与商户、支付宝签约三方协议
INVALID_PARAMETER 参数有误参数异常 请检查请求入参
PRODUCT_CODE_IS_INVALID 无效请求产品码,请求产品码必须为周期扣款 修改请求目标产品码,目标产品码为周期扣款
PRODUCTCODE_ALREADY_UPDATE 协议里产品码已经为周期性扣款 协议里产品码已经为周期性扣款,不能再修改
NOT_SUPPORTED_BUSINESS 现有协议里产品码已经不是通用代扣 请检查协议号是否正确,目前协议号的产品码不是通用代扣
SYSTEM_ERROR 系统繁忙 请重试或者联系技术支持查看
MERCHANT_AGREEMENT_IS_NOT_EXIST 商户协议不存在 添加商户协议
MERCHANT_STATUS_IS_NOT_NORMAL 商户协议状态不正常 检查商户协议
MERCHANT_AGREEMENT_IS_EXPIRED 商户协议过期了 检查商户协议
USER_AGREEMENT_IS_OUT_OF_DATE 用户协议过期 检查用户协议是否过期
USER_AGREEMENT_STATUS_IS_EXPIRED 用户协议状态不正常 检查用户状态
onlineServer