分账关系绑定

开发环境

http://dev-cn.your-api-server.com

POST

/v3/alipay/trade/royalty/relation/bind

当商户签约分账产品后，授权ISV帮其进行分账关系的维护。本接口用于商户与分账方的关系绑定。

公共错误码

业务错误码

状态码	错误码	错误描述	解决方案
400	SYSTEM_ERROR	系统繁忙	服务器异常可能发生了网络或者系统异常，导致服务调用失败，商户可以用同样的请求发起重试
400	INVALID_PARAMETER	参数有误	请根据接口返回的参数非法的具体错误信息，修改参数后进行重试
400	INVALID_RECEIVER_TYPE	分账收款方类型参数非法	请检查分账收款方类型参数
400	OPENID_APPID_NOT_MATCH	OPENID与APPID不匹配	检查当前接口调用时使用的appId与获取openId时使用的appId是否是同一个（需一致）
400	PRODUCT_UNSIGN	未签约分账产品	商户需在签约分账产品的情况下，才可进行分账关系集的新增操作。请先确认商户是否签约分账产品。
400	RECEIVER_ACCOUNT_NOT_CERTIFY	分账收款方账号未完成实名认证	请在支付宝完成实名认证，或更换一个已认证账号作为分账收款方
400	RECEIVER_ACCOUNT_NO_BALANCE	分账收款方账号无支付宝账户	分账收款方支付宝账号未开立余额账户，请确认收款方账号是否正确，更换账号后重新发起
400	RECEIVER_ACCOUNT_STATE_INVALID	分账收款方账号被冻结或已注销	分账收款方账号被冻结或已注销，请联系支付宝小二确认原因
400	RECEIVER_LIST_EMPTY	分账收款方列表为空	请检查分账收款方列表是否为空
400	RECEIVER_LIST_OVERLOAD	分账收款方列表数量超限	请检查分账收款方列表数量是否超过了20
400	RELATION_QUANTITY_LIMIT	达到分账关系集数量上限	分账关系集数量有上限，当达到上限后，无法继续添加分账方。可删除无用的分账方后，再发起分账关系绑定。
400	USERNAME_NOT_MATCH	分账接收方全称不匹配	请检查分账方全称是否正确
400	USER_NOT_EXIST	分账接收方不存在	请确认分账接收方类型或者账号无误后重试

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST 'http://dev-cn.your-api-server.com/v3/alipay/trade/royalty/relation/bind' \
--header 'authorization: ALIPAY-SHA256withRSA app_id=$appid,timestamp=$now,nonce=$uuid,expired_seconds=600,sign=$sign' \
--header 'alipay-request-id: $requestid' \
--header 'Content-Type: application/json' \
--data-raw '{
	"receiver_list":[
		{
			"type":"userId",
			"account":"2088xxxxx00",
			"name":"测试名称",
			"memo":"分账给测试商户",
			"login_name":"test@alitest.xyz",
			"bind_login_name":"test@alitest.xyz"
		}
	],
	"out_request_no":"2019032200000001"
}'

响应示例

{
	"result_code":"SUCCESS"
}

请求参数

Header 参数

authorization

string

必需

示例值:

ALIPAY-SHA256withRSA app_id=$appid,timestamp=$now,nonce=$uuid,expired_seconds=600,sign=$sign

alipay-request-id

string

必需

示例值:

$requestid

Content-Type

string

必需

示例值:

application/json

Body 参数application/json

receiver_list

array [object {6}]

必需

【描述】分账接收方列表，单次传入最多20个

type

string

可选

【描述】分账接收方方类型。【枚举值】支付宝账号对应的支付宝唯一用户号: userId 支付宝登录号: loginName 支付宝openId: openId 【示例值】userId

account

string

可选

【描述】分账接收方账号。当分账方类型是userId时，本参数为用户的支付宝账号对应的支付宝唯一用户号，以2088开头的纯16位数字；当分账方类型是loginName时，本参数为用户的支付宝登录号；当分账方类型是openId时，本参数传递支付宝openId信息。【示例值】2088xxxxx00

name

string

可选

【描述】分账接收方真实姓名。绑定分账关系时：当分账方类型是userId时，本参数可以不传，若上传则进行校验不上传不会校验。当分账方类型是loginName时，本参数必传。解绑分账关系时：作为请求参数可不填，分账关系查询时不作为返回结果返回【示例值】测试名称

memo

string

可选

【描述】分账关系描述【示例值】分账给测试商户

login_name

string

可选

【描述】作为查询返回结果：当前userId对应的支付宝登录号。当login_name与bind_login_name不相等时，表明该支付宝账户发生了登录号变更。【示例值】test@alitest.xyz

bind_login_name

string

可选

【描述】作为查询返回结果：分账收款方绑定时的支付宝登录号。分账关系绑定（alipay.trade.royalty.relation.bind）时，通过type为loginName绑定传入的支付宝登录号，若使用userId绑定则不返回。【示例值】test@alitest.xyz

out_request_no

string

必需

【描述】外部请求号，由商家自定义。32个字符以内，仅可包含字母、数字、下划线。需保证在商户端不重复。【示例值】2019032200000001

示例

返回响应

🟢200成功

application/json

Body

result_code

string

必需

【描述】SUCCESS：分账关系绑定成功； FAIL：分账关系绑定失败。【示例值】SUCCESS

修改于 2023-11-22 08:04:00

沙箱调试说明

分账关系解绑

分账关系绑定

公共错误码#

业务错误码#

请求参数

返回响应

公共错误码

业务错误码