koubei.trade.itemorder.buy(口碑商品交易购买接口)

口碑商品交易购买接口

公共参数

请求地址

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

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 koubei.trade.itemorder.buy
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
notify_url String 256 支付宝服务器主动通知商户服务器里指定的页面http/https路径。 http://api.test.alipay.net/atinterface/receive_notify.htm
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
out_order_no String 必选 64 商户订单号,64个字符以内、只能包含字母、数字、下划线;需保证在商户端不重复 A2018011200000001
subject String 必选 256 订单标题 星巴克礼品卡
biz_product String 必选 32 业务产品 ONLINE_PURCHASE
biz_scene String 必选 32 业务场景 giftCard
shop_id String 必选 64 门店ID 2015051100077000000000000300
buyer_id String 必选 32 买家支付宝ID 2088102015433735
timeout String 可选 6 该笔订单允许的最晚付款时间,逾期将关闭交易,取值范围:1m~30m(单位:分钟) 不传默认3m。 10m
total_amount Price 必选 9 订单总金额,单位为元,精确到小数点后两位,必须等于费用之和 100.00
promo_params String 可选 512 商户传入营销信息,具体值要和口碑约定,格式为json格式 {"kborder_flag":"xxxx"}
item_order_details ItemOrderDetail[] 必选 购买商品信息
sku_id String 必填 64 商品skuId 2015060400076000000000012100
original_price Price 必填 9 商品原价,单位元,精确到小数点后两位 50.00
price Price 必填 9 商品现价,即商品售价,单位为元,精确到小数点后两位 10.00
quantity Number 必填 6 购买商品数量 10

响应参数

参数 类型 是否必填 最大长度 描述 示例值
order_no String 必填 64 口碑订单号 20171114111040030100030100002400
trade_no String 必填 64 支付宝交易号,唤收银台时入参 2017122021001004560209558948
cashier_order_id String 选填 64 收银单id,唤收银台时传入,该参数为请求级别参数,如果二次支付,需要重新获取 201801171429447e00b7d293cd5ddErFwj0000053960

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
KoubeiTradeItemorderBuyRequest request = new KoubeiTradeItemorderBuyRequest();
request.setBizContent("{" +
"\"out_order_no\":\"A2018011200000001\"," +
"\"subject\":\"星巴克礼品卡\"," +
"\"biz_product\":\"ONLINE_PURCHASE\"," +
"\"biz_scene\":\"giftCard\"," +
"\"shop_id\":\"2015051100077000000000000300\"," +
"\"buyer_id\":\"2088102015433735\"," +
"\"timeout\":\"10m\"," +
"\"total_amount\":100.00," +
"\"promo_params\":\"{\\\"kborder_flag\\\":\\\"xxxx\\\"}\"," +
"      \"item_order_details\":[{" +
"        \"sku_id\":\"2015060400076000000000012100\"," +
"\"original_price\":50.00," +
"\"price\":10.00," +
"\"quantity\":10" +
"        }]" +
"  }");
KoubeiTradeItemorderBuyResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "koubei_trade_itemorder_buy_response": {
        "code": "10000",
        "msg": "Success",
        "order_no": "20171114111040030100030100002400",
        "trade_no": "2017122021001004560209558948",
        "cashier_order_id": "201801171429447e00b7d293cd5ddErFwj0000053960"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

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

业务错误码

公共错误码

错误码错误描述解决方案
INVALID_PARAMETER 参数有误 请参考接口文档检查入参信息
SYSTEM_ERROR 系统繁忙 系统繁忙,请稍后重试
SHOP_NOT_EXIST 门店不存在 请检查传入的门店是否已经入驻口碑
ITEM_NOT_EXIST 商品不存在 请检查传入的商品是否已经发布
ILLEGAL_ITEM_STATUS 商品状态非法 商品必须上架状态:EFFECTIVE才能购买
ILLEGAL_ITEM_ORIGINAL_PRICE 传入的商品原价与商品实际原价不一致 请检查传入的原价是否有误
ITEM_NOT_DURING_SALES_PERIOD 商品不在售卖周期内 请检查商品是否在售卖周期内
ILLEGAL_ITEM_PRICE 传入的商品现价与商品实际现价不一致 请检查传入的商品现价是否有误
USER_HAS_UNPAID_ORDER 用户有未支付的订单 用户有未支付的订单,可以引导用户完成支付或关闭订单再下单
ILLEGAL_SHOP_STATUS 门店状态非法 门店必须是营业状态(OPEN),请检查传入门店的状态
ITEM_NOT_BELONG_TO_PID 传入的商品不属于当前商户 请检查传入商品的归属商户。
SHOP_NOT_BELONG_TO_PID 门店不归属当前商户 请检查传入门店是否归属当前商户
USER_NOT_EXIST 买家不存在 请检查买家(buyer_id)是否是正确的支付宝账号
USER_NOT_REAL_NAMED 买家没有实名制 引导用户实名制后购买
ITEM_QUANTITY_OVER_LIMITATION 购买商品的数量超过限制 请限制用户购买数量
ITEM_TYPE_OVER_LIMITATION 购买商品的种类超过限制 请限制用户购买商品的种类
SENSITIVE_WORDS_VALIDATE_FAIL 入参有敏感词 检查入参信息是否有敏感词
MERCHANT_NOT_SIGN 商户未签约 商户需先完成签约
ITEM_NOT_ALLOWED_SALE_ON_SHOP 传入的商品不允许在传入的门店上售卖 请检查商品、门店的售卖关系
NOT_DUPLICATED_REQ 请求重入(out_order_no、partner_id相同),但是业务信息不同 请求重入时,确保传入的业务信息和第一次请求传入的一样
BUSINESS_ERROR 未知原因的业务异常 请联系技术支持
NO_EXTERNAL_TICKET_INVENTORY_ID 商品未设置外部卡码库id 如果是外部卡码业务场景,商品必须设置外部卡码库id,否则不能购买
INVENTORY_NOT_ENOUGH 商品库存不足 商品库存不足,无法购买

触发通知类型

通知类型描述默认开启
order_action_notify 订单操作通知 0

触发通知示例

https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync&notify_id=91722adff935e8cfa58b3aabf4dead6ibe&notify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&out_order_no=A2018011200000001&partner_id=2088102015433132&order_no=20171114111040030100030100002400&trade_no=2017122021001004560209558948&gmt_payment=2018-01-12 21:10:10&order_status=WAIT_PAY&notify_action=PAY_APPLY:支付申请; DELIVER:发货成功;CLOSE:主动关单,TIMEOUT_CLOSE:超时关单
onlineServer