通用场景
通知商家发放三方凭证
发码成功,则必须在响应中直接返回正确的券码。商户返回参数错误或发码失败,支付宝侧会在5分钟内多次重试发码请求。5分钟后仍然发码失败,则支付宝侧会发起退款处理。
公共请求参数
业务请求参数
body参数
biz_type|凭证关联的主体类型必选string(32)
【描述】发放凭证时所代表的业务主体类型,如支付宝商品。由商家传入支付宝,并在此接口将相关数据返回,标识需要发放的凭证类型。
【枚举值】
支付宝商品: alipay_merchandise
【示例值】alipay_merchandise
order_id|支付宝订单号必选string(64)
【描述】购买商家业务主体时的营销订单号,如购买商品的订单号。
【示例值】2015042321001004720200028594
以下参数 二选一 传入
user_id|用户idstring(32)
【描述】用户uid
新商户建议使用open_id替代该字段。对于新商户,user_id字段未来计划逐步回收,存量商户可继续使用。如使用open_id,请确认 应用-开发配置-openid配置管理 已启用。无该配置项,可查看openid配置申请。
【示例值】2088xxxx
open_id|开放用户idstring(128)
【描述】开放id,基于商家appid生成的用户id。 详情可查看 openid简介
【示例值】074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5
out_order_id|商家自定义订单号可选string(1024)
【描述】商家自定义订单号。与接口传入的out_order_id一致
【注意事项】该字段由商户传入,使用前请务必确认是否正确!
【示例值】20150320010101001
order_amount|订单金额可选price(16)
【描述】商品订单金额
【示例值】30.00
trade_no|支付宝交易流水号可选string(64)
【描述】购买订单的交易流水号
【示例值】2021042322001426261436764012
send_item_info_list|待发放的商品信息可选senditeminfo[]
【描述】凭证所关联的商品信息,传入信息与商家申报进入支付宝的商品信息一致,商家依据此数据生成商家的三方凭证。
item_id|支付宝的商品信息必选string(64)
【描述】支付宝平台侧商品id
【示例值】2023010122000000000001
count|发放数量必选number(10)
【描述】需要商家发码的数量
【示例值】1
start_time|有效期开始时间必选number(10)
【描述】时间戳,秒
【示例值】1681711390
end_time|有效期结束时间必选number(10)
【描述】时间戳,秒
【示例值】1681711390
out_item_id|商家侧商品id可选string(100)
【描述】商家侧商品id
【示例值】123
out_sku_id|商家侧sku id可选string(128)
【描述】商家侧sku id
【示例值】12345
sku_id|支付宝平台侧sku id可选string(64)
【描述】支付宝平台侧sku id
【示例值】2023010123000000000001
title|商品名称可选string(60)
【描述】商品名称
【示例值】美味甜甜圈
phone_number|用户手机号可选string(512)
【描述】用户在下单时传入的手机号码
【注意事项】手机号码为加密数据,加解密请参考文档 https://opendocs.alipay.com/common/02mse3 ,请商家/服务商保护好用户手机号码的数据安全和隐私。
【示例值】12312341234
常见请求示例
默认示例
curl -x post 'spi_implementation_url?sign=${sign}&method=spi.alipay.marketing.certificate.certification.send&charset=utf-8&version=1.0&utc_timestamp=${now}&sign_type=rsa2' \
--header 'content-type: application/x-www-form-urlencoded;charset=utf-8' \
--data-urlencode 'user_id=2088xxxx' \
--data-urlencode 'open_id=074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5' \
--data-urlencode 'biz_type=alipay_merchandise' \
--data-urlencode 'out_order_id=20150320010101001' \
--data-urlencode 'order_amount=30.00' \
--data-urlencode 'trade_no=2021042322001426261436764012' \
--data-urlencode 'send_item_info_list=[{"out_sku_id":"12345","start_time":1681711390,"item_id":"2023010122000000000001","out_item_id":"123","count":1,"end_time":1681711390,"sku_id":"2023010123000000000001","title":"美味甜甜圈"}]' \
--data-urlencode 'phone_number=12312341234' \
--data-urlencode 'order_id=2015042321001004720200028594'
说明:spi_implementation_url是开发者在开放平台实现spi接口时填写的后端服务地址,详情请查看
业务响应参数
response
code必选string
【描述】错误码,只有两种:
成功-10000
失败-40004
返回其他值会被认为非法响应,区分大小写。
成功-10000
失败-40004
返回其他值会被认为非法响应,区分大小写。
【示例值】40004
msg必选string
【描述】错误描述,只有两种:
成功-success
失败-business failed
返回其他值会被认为非法响应,区分大小写。
成功-success
失败-business failed
返回其他值会被认为非法响应,区分大小写。
【示例值】business failed
user_id|支付宝uid必选string(32)
【描述】购买商家业务主体的用户uid
新商户建议使用open_id替代该字段。对于新商户,user_id字段未来计划逐步回收,存量商户可继续使用。如使用open_id,请确认 应用-开发配置-openid配置管理 已启用。无该配置项,可查看openid配置申请。
【示例值】2088xxxx
open_id|支付宝openid必选string(128)
【描述】买家的支付宝openid 详情可查看 openid简介
【示例值】074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5
result_code|发放凭证结果必选string(16)
【描述】商家发放凭证的结果,支付宝会依此字段决策是否处理结果。
【枚举值】
发码成功: success
发码失败: fail
券码发放中: processing
【注意事项】当返回值为processing时,后续需在10min内调用发码回调接口回传券码
【示例值】success
send_code_result_list|商家发放券码结果列表特殊可选sendcoderesult[]
【描述】商家发放券码结果列表,需要和要求发码数量的结果保持一致,否则会认为发码失败
【注意事项】result_code=success时必填
code|服务商发放的三方码必选string(64)
【描述】服务商发奖后返回的券码列表
【注意事项】限制: 单个code最长64位。 商户上传的券code列表,code允许包含的字符有0-9、a-z、a-z、-、_、 、=、|。 如果发生券码后校验不通过.支付宝内部不会进行发奖。针对这种case会通知服务商进行整改,该笔交易支付宝内部不会发奖成功。
【示例值】123ab
out_item_id|商家侧商品id必选string(128)
【描述】商家侧商品id
【示例值】123
item_id|支付宝的商品信息必选string(128)
【描述】支付宝的商品信息
【示例值】2023010122000000000001
out_sku_id|商家侧sku id必选string(128)
【描述】商家侧sku id
【示例值】12346
sku_id|支付宝平台侧sku id必选string(128)
【描述】支付宝平台侧sku id
【示例值】2023010123000000000001
qr_code|三方码二维码值可选string(512)
【描述】三方码二维码值,可填入url或字符串。长度不能超过512。
【示例值】alipays://platformapi/startapp?appid=xxx
sub_code可选string
【描述】业务错误码,在业务失败的情况下返回,与 spi 接口文档里的“业务错误码”保持一致,值不能为 null 或 “”,在业务成功的情况下不能返回。
【示例值】invalid_params
sub_msg可选string
【描述】业务错误描述,在业务失败的情况下返回。
【示例值】无效参数
order_no|支付宝订单号可选string(64)
【描述】购买商家业务主体的营销订单号。
【注意事项】已废弃,该字段无需返回
【示例值】2015042321001004720200028594
sign必选string
【描述】签名,详见
【示例值】dzxh8eetuahoye3w1j poiphfdxoybfunn1lket/v7p4zjdyojwea6izs6hz0ydw5cp/viufub5i0/v5wens3oyr8zredqo6d futdlhdc efyckiqhbxizgngpdpdfp1pis7bdhhzrszhbrqb7o4k3dxc aanfauu4v6zdwczo=
响应示例
正常示例
异常示例
{
"response": {
"code": "10000",
"msg": "success",
"user_id": "2088xxxx",
"open_id": "074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5",
"result_code": "success",
"send_code_result_list": [
{
"code": "123ab",
"out_item_id": "123",
"item_id": "2023010122000000000001",
"out_sku_id": "12346",
"sku_id": "2023010123000000000001",
"qr_code": "alipays://platformapi/startapp?appid=xxx"
}
]
},
"sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}
说明:本示例仅供参考。
业务错误码
错误码 | 错误描述 | 凯发app官方网站的解决方案 |
---|---|---|
system_error | 系统繁忙 | 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 |
invalid_parameter | 参数有误,请检查参数 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 |
certificate_send_fail | 凭证发放失败 | 凭证发放操作失败,可以用同样的请求发起重试 |
接口工具
spi使用文档
获取sdk