同步凭证核销状态

开发环境

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

POST

/v3/alipay/marketing/certificate/certification/use

商户调用该接口，通过订单号及三方码进行本地商品凭证核销，接口同步返回核销结果。

公共错误码

业务错误码

状态码	错误码	错误描述	解决方案
400	SYSTEM_ERROR	系统繁忙	可能发生了网络或者系统异常，导致服务调用失败，商户可以用同样的请求发起重试
400	INVALID_PARAMETER	,请检查参数	请根据接口返回的参数非法的具体错误信息，修改参数后进行重试
400	CERTIFICATE_IS_INVALID	凭证已作废	对应的凭证已经作废，不能再核销，修改入参后进行重试。
400	CERTIFICATE_IS_USED	凭证已核销	对应的凭证已经被核销，不能再次核销，修改入参后进行重试。
400	CERTIFICATE_NOT_EXIST	凭证不存在或未发放	对应的凭证不存在，修改入参后进行重试。

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST 'http://dev-cn.your-api-server.com/v3/alipay/marketing/certificate/certification/use' \
--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 '{
	"biz_dt":"2023-09-07 18:42:10",
	"certificate_use_info_list":[
		{
			"code":"YHQ251847751237542"
		}
	],
	"order_id":"2023090701502300000005940087259495",
	"out_biz_no":"a879f99e-1494-4d4a-b125-e526027ee5ce",
	"shop_id":"2023090700502007040026779831",
	"user_id":"2088912480905594"
}'

响应示例

200 - 成功示例

{
	"certificate_use_result_list":[
		{
			"certificate_id":"2021042322001426261436764012",
			"code":"124AB",
			"encrypted_code":"LLyABKAESLgosRSH/OAfU5",
			"use_order_no":"2023052100445005835800000045",
			"result":"SUCCESS",
			"msg":"核销成功",
			"out_order_id":"2023073101",
			"order_id":"1997081101502300000001290055702988",
			"amount_info":{
				"original_price":"10.00",
				"sale_price":"5.00",
				"receipt_amount":"4.00"
			},
			"serial_info_list":{
				"serial_no":"11111",
				"amount_info":{
					"original_price":"10.00",
					"sale_price":"5.00",
					"receipt_amount":"4.00"
				}
			}
		}
	]
}

请求参数

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

biz_dt

string

必需

【描述】核销时间。格式为：yyyy-MM-dd HH:mm:ss 【注意事项】支付宝的核销时间以外部核销的时间为准，防止极限情况导致凭证无法核销。商家需保证核销时间的准确性【示例值】2023-01-01 00:00:00

certificate_use_info_list

array [object {1}]

必需

【描述】凭证核销详情

code

string

可选

【描述】三方码。取值为支付宝调用凭证发放spi时商户返回的三方码【注意事项】encrypted_code与code必须且只能二选一【示例值】123AB

order_id

string

必需

【描述】购买商品的订单id。平台码模式从核销准备接口获取【注意事项】三方码核销时该值必传【示例值】2021042322001426261436764012

out_biz_no

string

必需

【描述】外部业务单号，用作幂等控制。幂等作用：参数不变的情况下，再次请求返回与上一次相同的结果。外部接入方需保证业务单号唯一。【示例值】20170101000001654bb46ba

shop_id

string

必需

【描述】核销门店id 【示例值】202104232200142626143676

user_id

string

必需

【描述】凭证归属支付宝用户id。平台码模式从核销准备接口获取【示例值】2088XXXXX

示例

返回响应

🟢200成功

application/json

Body

certificate_use_result_list

array [object {10}]

必需

【描述】凭证核销结果

certificate_id

string

必需

【描述】凭证id 【示例值】2021042322001426261436764012

code

string

必需

【描述】三方码【示例值】124AB

encrypted_code

string

必需

【描述】核销准备返回的支付宝平台加密券码【示例值】LLyABKAESLgosRSH/OAfU5

use_order_no

string

必需

【描述】核销操作单号,核销成功必填,撤销核销使用【示例值】2023052100445005835800000045

result

string

必需

【描述】核销结果枚举【枚举值】核销成功: SUCCESS 凭证不是可核销状态: CERTIFICATE_CANNOT_USE 商品不在可用商品范围内: NOT_IN_AVAILABLE_ITEM 更多【示例值】SUCCESS

msg

string

必需

【描述】结果说明【示例值】核销成功

out_order_id

string

必需

【描述】商家侧核销对应的交易订单id 【示例值】2023073101

order_id

string

必需

【描述】购买商品的订单id。【示例值】1997081101502300000001290055702988

amount_info

object

可选

CertificateInstanceAmountInfo 【描述】凭证实例的金额信息，在异常场景下可能为空，需要判断是否有值才可进行使用。【注意事项】在网络异常的场景下此字段可能为空，商家需要保证对此字段非强诉求。

serial_info_list

object

可选

【描述】本次核销的次序号信息

🟠400请求有误

修改于 2023-11-22 02:06:05

凭证核销准备

撤销凭证核销状态

同步凭证核销状态

公共错误码#

业务错误码#

请求参数

返回响应

公共错误码

业务错误码