已更新更新时间：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公域收费场景值。引入前置优惠组件小程序交易组件 提供组件帮助商家获取商品详情、订单下单页上的商品优惠信息，该组件在开通 小程序交易组件 时已经绑定完成，无需进行二次操作。在引入组件之后，能够获取当前商品和订单的支付优惠，包括商家支付券、红包、会员积分优惠、消费金等；在组件接入中的商品参数请注意与商品库的商品信息一致。声明组件在小程序项目的根目录 app.json 中声明 小程序交易组件 。tradepay 指组件名，支持由用户自行定义，使用组件时以 自定义名称 为准。在页面中初始化获取实例1requireplugin 引入交易组件。2在页面启动的生命周期 onload 中创建交易组件实例。3.then 获取实例，通过全局变量保存起来后续使用。注意：初始化需要传入订单咨询的参数。实例方法方法名描述getdiscountinfo获取优惠信息。详情可查看 。展示前置优惠下单页 .axml可以传入 style、class 来调整样式。获取优惠信息可通过 getdiscountinfo 获取平台优惠信息。注意：请确保 payinst 已经通过初始化函数 createenhancedtradepay 赋值。本地测试验证当咨询出 优惠金额大于0 时，优惠咨询组件才会展示出来，为了方便在本地研发调试的时候，可以通过forceshow=true强制展示来调整组件的样式、位置。注意：调试完成后请删除掉这个配置，否则无法展示出具体的金额。服务端接入业务流转状态说明接口调用流程创单创建商家侧订单开发者可在小程序端调用 my.request 接口连接到商家服务端，发送用户订单数据至服务端。示例代码创建业务订单在服务端调用 alipay.open.mini.order.create（订单创建接口），获得 小程序交易组件 业务订单号 order_id。虚拟商品类业务订单类型中 merchant_biz_type 为 virtual_recharge。示例代码重要入参说明 英文名称类型描述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订单类型，决定后续履约节点中的参数校验规则，必填。虚拟商品场景固定为virtual_rechargepathstring商家小程序对应的订单详情页路径地址 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物流类型，虚拟商品字段为 virtual重要出参说明英文名称描述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。subjectstring商品的标题/交易标题/订单标题/订单关键字等。 不可使用特殊字符，如 /,=,& 等。total_amountstring必填，订单总金额，单位为元，精确到小数点后两位，取值范围 [0.01,100000000]。buyer_id（buyer_open_id）string小程序支付必填，付款用户的支付宝 id，获取详情可查看 用户授权文档。seller_idstring卖家支付宝用户 id。可登录 > 主账号信息 > 账号 id 获取。notify_urlstring接收的异步通知 http/https 路径地址。用户支付成功时，支付宝将向本地址发送异步通知。out_trade_nostring必填，商户订单号。由商家自定义，64个字符以内，仅支持字母、数字、下划线且需保证在商户端不重复。extend_paramsstringextend_params.trade_component_order_id：小程序公域商品交易场景中该参数必传，即业务订单号 order_id。重要出参说明英文名称描述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（统一收单线下交易查询）返回值为准。●其他有关异步通知的问题可查看 。●若未成功接收到异步通知，排查方法可查看 。履约交易组件提供订单状态推进和变更的接口，商家在订单状态关键节点变化时，调用本组接口实现对订单资金的结算，并向用户下发消息提醒召回用户，给予用户更好的体验。订单发货/充值商家完成虚拟商品发货/充值动作之后，调用 同步订单发货。注意：虚拟商品类型在发货时 delivery_list 无需传参。示例代码充值完成/确认收货商家基于线上系统触发虚拟商品充值成功或者发送完成后，可调用 对该笔订单更新履约状态，在确认收货时，用户将收到消息提醒。示例代码注意：在确认收货这个履约节点时，商家需要调用交易组件的确认收货接口进行业务处理。充值完成和订单发货/充值是有前后依赖的接口，如果对一笔订单没有调用发货接口，则调用充值完成/确认收货接口会失败。订单结算通知当交易完成后，根据不同的商品交易类型，由商家通过发货、确认收货完成订单的履约状态之后，根据不同商品类目的结算周期，对订单资金进行结算。在结算完成时将通过 alipay.open.mini.order.settle.notify（结算消息通知接口）向商家发送结算消息通知 。辅助接口支付单退款当交易发生之后一段时间内，由于买家或者商家的原因需要退款时，商家可以调用 通过商家网站唯一订单号 out_trade_no 或支付宝交易号 trade_no，将对应订单支付款退还给买家，支付宝将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家账号上。 注意：●交易超过约定时间（签约时设置的可退款时间）的订单无法进行退款。●一笔退款失败后重新提交，要采用原来的退款单号。●refund（需要退款的金额），该金额不能大于订单金额，单位为元，支持两位小数。●同一笔订单如需分多次退款，需传入 out_request_id 标识一次退款请求，同一笔交易多次退款需保证该值唯一（即分次退款需保证 order_id 不变，每次退款请求都需传入不同 out_refund_id）。●交易单全额退款后，业务订单也会随之关闭。支付单关单当交易创建后，用户如果在一定时间内未进行支付，商家可调用 通过商家网站唯一订单号 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 批量查询对应订单支付情况。
