已更新更新时间：2025-01-07 14:02:08文档更新记录 >接入助手收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档概述面向以实物商品售卖为主营业务，支持全国配送、本地外卖、到店自提等履约模式的数字零售行业商户。完成 后，商家/服务商可根据本文指引快速接入 小程序交易组件 。●小程序交易组件 支持自研商家/服务商通过 自研应用 或 第三方应用 代调用方式，调用 api 接入。●小程序交易组件 支持在 完成单步/链路测试。●小程序交易组件 完成开发后，可根据 进行验收。订阅消息设置接收消息的应用网关地址支付宝会通过 from 蚂蚁消息服务使用 向商家自研应用或第三方应用设置的 应用网关 地址，post 方式推送商家/服务商使用 小程序交易组件 的异步通知消息。若商家/服务商网络环境比较复杂，如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。订阅消息接口商家/服务商需根据 订阅消息 指引，为接入交易组件的 自研应用 或 第三方应用 订阅如下消息接口。注意：●仅完成订阅后才会收到支付宝发送的对应异步通知消息。●商家/服务商 可通过消息通知中 msg_method 参数判断消息类型。消息接口英文名消息接口中文名说明alipay.open.mini.order.changed订单结果通知接口同步订单的状态变更结果。alipay.open.mini.order.settle.notify结算消息通知接口同步订单在履约账期结束后，资金结算到商家余额户的结果。前端接入小程序前端需要完成以下步骤，将业务订单信息、商品/订单优惠信息获取并返回给服务端进行相应处理。判断订单创建环境请在创建订单前调用 （订单前置判断接口）来判断是否需要使用交易组件创建订单。示例代码重要出参说明英文名称类型描述requireorderenum是否需要创建交易组件订单，生成 order_id 传入支付单。1：需要，当前交易场景为公域。0：不需要，当前交易场景不需要同步业务订单。sourceidstring跟踪 id，需要获取之后创建业务订单时传入。sceneidstring公域收费场景值。引入扩展组件商家的小程序可以使用 前置优惠组件、商品详情页组件，来帮助商家在小程序中提前向用户展示商品的优惠信息，提升用户的下单成交意愿。商家可以按需组合使用，支持在商家小程序的 商品详情页、商品订单页 中提前展示订单优惠，目前支持的优惠类型包括：●专享价●消费金商品●支付宝会员积分购，支付宝会员专享价●优惠券，红包等优惠接入详情可查看 。说明：前置优惠组件 开通 小程序交易组件 时已完成订购，商品详情页 订购可查看 。服务端接入业务流转状态说明接口调用流程创单创建商家侧订单开发者可在小程序端调用 my.request 接口连接到商家服务端，发送用户订单数据至服务端。示例代码创建业务订单在服务端调用 alipay.open.mini.order.create（订单创建接口），获得 小程序交易组件 业务订单号 order_id。数字零售类业务订单类型中 merchant_biz_type 为 kx_shopping。示例代码重要入参说明英文名称类型描述out_order_idstring商家外部订单号。 需要和 alipay.trade.create（统一收单交易创建接口）中的out_trade_no保持一致。titlestring商品的标题/交易标题/订单标题/订单关键字等。 不可使用特殊字符，如 /,=,& 等。total_pricestring必填，订单总金额，单位为元，精确到小数点后两位，取值范围 [0.01,100000000]。buyer_id（buyer_open_id）string小程序支付必填，付款用户的支付宝 id，获取详情可查看 用户授权文档。seller_idstring卖家支付宝用户 id。可登录 > 主账号信息 > 账号 id 获取。merchant_biz_typestring订单类型，决定后续履约节点中的参数校验规则，必填。数字零售场景固定为 kx_shopping。pathstring商家小程序对应的订单详情页路径地址 value。仅需传入小程序页面路径即可。同一笔订单的链接必须与第一次传入的地址相同，且需是小程序内部页面路径，例如：/pages/index/index?orderid=10190608609185。order_detail.item_infos.out_sku_idstring商家商品 sku_id，若是提报到商品库的商品，order_detail.item_infos.out_sku_id 和 order_detail.item_infos.out_item_id 必传。order_detail.item_infos.out_item_idstring商家商品 id，若是提报到商品库的商品，order_detail.item_infos.out_sku_id 和 order_detail.item_infos.out_item_id 必传。source_idstring追踪 id，公域分发场景必传，会影响主播归因、分享员归因等。通过调用 接口返回。本地外卖/自提模式说明参数类型说明delivery_detail.delivery_typestring本地配送订单类型为 express，自提订单类型为 selfpick。delivery_detail.delivery_timestring商家可传入预计配送时间，格式为 2023年5月31日 11:00-12:00重要出参说明英文名称描述order_id交易组件订单号。可以把获取到的order_id作为alipay.trade.create（统一收单交易创建接口）extend_params.trade_component_order_id的入参进行关联。out_order_id外部商户订单号数字零售下单数字零售带优惠下单数字零售带收货地址下单创建支付单商家服务端调用 alipay.trade.create（统一收单交易创建接口）得到支付宝交易号trade_no 为小程序唤起收银台使用，其中 extend_params.trade_component_order_id需要传入 创建业务订单 步骤中获取的订单号 order_id。注意：在创建业务订单后，需在 1 分钟内创建支付单，并通过传入 trade_component_order_id 将业务订单和支付单进行关联。如一笔业务订单未关联支付单，24 小时后会自动关闭。示例代码重要入参说明英文名称类型描述out_trade_nostring必填，商户订单号。需要和 alipay.open.mini.order.create（订单创建接口）里面的 out_order_id 保持一致。product_codestring必填，交易组件场景只支持产品码 jsapi_pay。extend_params.trade_component_order_idstring小程序公域商品交易场景中该参数必传，即业务订单号order_id。op_app_idstring小程序经营主体 appid，指商家在小程序中，拉起收银台支付时，对应的小程序应用的 appid。●经营主体与收款主体是同主体时，无需提前关联绑定。●经营主体与收款主体是不同主体时，需要提前关联绑定，才可以生效使用。subjectstring商品的标题/交易标题/订单标题/订单关键字等。 不可使用特殊字符，如 /,=,& 等。total_amountstring必填，订单总金额，单位为元，精确到小数点后两位，取值范围 [0.01,100000000]。alipay.open.mini.order.create（订单创建接口）中的 order_detail.price_info.order_price 保持一致。buyer_id（buyer_open_id）string小程序支付必填，付款用户的支付宝 id，获取详情可查看 用户授权文档。seller_idstring卖家支付宝用户 id。可登录 > 主账号信息 > 账号 id 获取。notify_urlstring接收的异步通知 http/https 路径地址。用户支付成功时，支付宝将向本地址发送异步通知。重要出参说明英文名称描述out_trade_no外部商户支付单号trade_no支付宝交易号。小程序唤起收银台时入参 tradeno 的值。支付唤起收银台在小程序端调用 接口传入 tradeno，唤起支付宝收银台，引导用户完成支付。示例代码异步通知订单支付成功时，商家可以通过在 alipay.trade.create（统一收单交易创建接口）设置异步通知（notify_url）来获得支付宝服务端返回的支付结果，当异步通知中返回的 trade_status（交易状态）为 trade_success 时，表示支付成功。收到异步通知后需通过 printwriter 类打印输出 success。如果商家反馈给支付宝的字符不是success 这 7 个字符，支付宝服务器会不断重发通知，直到超过 24 小时 22 分钟。一般情况下，25 小时以内完成 8 次通知（通知的间隔频率一般是：4m，10m，10m，1h，2h，6h，15h）。注意：●开发者设置的 notify_url 需要为外部网络环境可正常访问的网址，且状态码为 200，支付结果请以异步通知或 alipay.trade.query（统一收单线下交易查询）返回值为准。●其他有关异步通知的问题可查看 。●若未成功接收到异步通知，排查方法可查看 。●若订阅了业务单 状态变更消息，则会接收到 status='paid' 状态变更通知。履约交易组件提供订单状态推进和变更的接口，商家在订单状态关键节点变化时，调用本组接口实现对订单资金的结算，并向用户下发消息提醒召回用户，给予用户更好的体验。订单发货商家完成发货动作之后，调用 同步订单发货。示例代码注意：●通过交易组件下单的订单，同步给订单中心时，只会同步订单支付成功的订单，商家不必将订单发货、确认收货和发起售后的三种状态同步给订单中心。其中 delivery_list.delivery_id 字段为物流编码，详情可查看 。●若订阅了业务单 状态变更消息，则会接收到 status='delivered' 状态变更通知。本地外卖/自提模式说明物流信息 delivery_detail 中，物流类型 delivery_detail.delivery_type 本地配送订单类型为 express，自提订单类型为 selfpick。如为自提订单 selfpick 时，则 delivery_list 参数不可传。确认收货商家基于快递物流状态识别用户已经确认收货后，可调用 对该笔订单更新履约状态，在确认收货时，用户将收到消息提醒。示例代码注意：●在确认收货这个履约节点时，商家需要调用交易组件的确认收货接口进行业务处理。●确认收货和发货是有前后依赖的接口，如果对一笔订单没有调用发货接口，则调用确认收货接口会失败。●若订阅了业务单 状态变更消息，则会接收到 status='received_confirm' 状态变更通知。订单结算通知当交易完成后，根据不同的商品交易类型，由商家通过发货、确认收货完成订单的履约状态之后，根据不同商品类目的结算周期，对订单资金进行结算。在结算完成时将通过 alipay.open.mini.order.settle.notify（结算消息通知接口）向商家发送结算消息通知 。辅助接口支付单退款当交易发生之后一段时间内，由于买家或者商家的原因需要退款时，商家可以调用通过商家网站唯一订单号 out_trade_no 或支付宝交易号trade_no，将对应订单支付款退还给买家，支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。 注意：●交易超过约定时间（签约时设置的可退款时间）的订单无法进行退款。●支付宝退款支持单笔交易分多次退款，多次退款需要提交原支付订单的订单号和设置不同的退款请求号 out_request_no。●一笔退款失败后重新提交，要保证重试时退款请求号 out_request_no 不变，防止该笔交易重复退款。○同一笔交易的退款至少间隔 3s 后发起。●同一笔交易累计提交的退款金额不能超过原始交易总金额，单位为元，支持两位小数。●交易单全额退款后，业务订单也会随之关闭。●若订阅了业务单 状态变更消息，则会接收到 status='refund_closed' 状态变更通知。支付单关单当交易创建后，用户如果在一定时间内未进行支付，商家可调用 通过商家网站唯一订单号 out_trade_no 或支付宝支付单号trade_no 关闭，将对应未付款的交易进行关闭。查询支付单信息商家可调用 alipay.trade.query（统一收单线下交易查询接口），通过商家网站唯一订单号 out_trade_no 或支付宝支付单号trade_no 查询对应订单支付情况。查询订单信息商家可调用 alipay.open.mini.order.query（查询订单接口），通过商家网站唯一订单号 out_order_id 或支付宝支付单号 order_id 查询对应订单支付情况。示例代码查询订单对账列表信息商家可调用 alipay.open.mini.order.itembill.batchquery（查询小程序订单对账列表信息接口），通过小程序 app_id 批量查询对应订单支付情况。
