• 下载
  • 社区

小程序订单中心

产品介绍

概述


小程序订单中心是面向 C 端用户提供的小程序交易服务产品。商户回传订单信息后,用户在小程序内下单支付,可以通过订单中心小程序完成查看消费明细、快速联系商家、咨询售后相关问题等操作;完成交易后,用户还可对此次消费体验进行评价和打分。


产品特色


  • 订单中心在为用户提供交易服务的同时,也为商家的小程序提供了流量入口,提高用户的活跃度和留存率。
  • 用户可快速进入商家的小程序及对应的商品详情页,商家可利用此入口来提升会员复购率或给予会员权益。


0000.png

商家小程序入口


我的小程序

商户同步小程序订单后,用户可在“我的小程序”页面收到订单消息提醒,点击跳转到商户小程序订单详情页。

image.png


支付助手

商户通过交易接口实时同步小程序订单信息后,用户支付成功后会收到一条“服务提醒”内的支付消息,在服务提醒页面可以点击“查看订单详情”跳转到订单中心小程序查看订单详情页。订单实时同步接入方式见下方接入指引“第五步”

image.png


账单

用户在小程序内支付成功后,可在支付宝客户端选择 我的 > 账单 进入账单详情页上的入口跳转到订单中心小程序查看订单详情页。


订单中心.png


用户在“订单中心”中有两种方式进入商家的小程序首页:列表页和详情页。在详情页,用户还可以通过点击 查看订单明细 查看订单详情。


注意:

为了顺利实现到小程序的跳转,商家或开发者需要进入小程序开发中心 设置 > 基础设置 > 小程序相互跳转 中设置为“允许所有小程序跳转”。


0001.png


商家权益


商家回传订单信息后,小程序平台会根据小程序的 UV(独立访客数量) 和订单、服务质量等因素来综合评估给予以下权益。

注意:

以下权益目前采用定向机制,暂不支持主动申请,商家在回传订单信息时请参考下文的《订单明细同步规范》。


搜索运营

商家同步订单信息后,符合搜索运营准入条件的,可在小程序管理后台 运营中心 > 搜索推广 > 搜索运营 页面申请搜索服务,具体准入条件及配置方式,请点击查看 小程序搜索服务

商户同步的商品信息可作为小程序搜索关键词,用户搜索商品名称/服务名称即可找到商家的小程序。


支付助手

商家通过支付接口实时同步订单后,在支付助手消息中会露出 查看订单详情 入口,用户点击可复访到商家小程序的订单详情页查看明细。


其他权益(待开放)

后续会陆续开放更多权益给到商户,敬请期待!


准入条件


商家需满足以下条件,用户在小程序内支付成功后,可在订单中心中查看订单:

1、个人工商户(个人账号)和企业账号均可申请;

2、商家需接入 小程序支付 产品;

3、商家需在用户支付成功后,通过接口同步此笔交易明细(如商品图片、商品名称、物料信息、订单详情 URL 等)。


计费模式


不收费。


接入指引

第一步:创建小程序

要在您的小程序内使用 订单中心 功能,您需要首先完成 开发者入驻 并 创建小程序


第二步:添加功能

小程序创建完成后,开发者在 功能列表 部分可以点击 添加功能 来添加 小程序订单中心 功能。勾选相应功能后,点击 确定 即可添加功能。


第三步:签约功能

小程序订单中心 功能需要签约才能生效,开发者添加功能后,点击功能列表右侧 签约,提交相关信息

完成签约后,需要 1 个工作日左右的审核时间(审批结果会以短信和邮件形式告知),待审核完毕后,功能的状态会变成 已生效,即可使用 小程序订单中心 功能。


幻灯片1.PNG


第四步:集成并配置 SDK

服务端 SDK 需要商户集成在自己的服务端系统中,用于后续的服务端接口调用。


下载服务端 SDK

为了帮助开发者调用开放接口,我们提供了 开放平台服务端 SDK,包含 JAVA、PHP、NodeJS、Python 和 .NET 五种语言,封装了签名 & 验签、HTTP 接口请求等基础功能。

请先下载对应语言版本的 SDK 并引入您的开发工程。


接口调用配置

在 SDK 调用前需要进行初始化,以 JAVA 代码为例:


1AlipayClient alipayClient = new DefaultAlipayClient(URL,APP_ID,APP_PRIVATE_KEY,FORMAT,CHARSET,ALIPAY_PUBLIC_KEY,SIGN_TYPE);


关键参数说明:

配置参数示例值解释获取方式/示例值
URL支付宝网关(固定) https://openapi.alipay.com/gateway.do 
APPIDAPPID 即创建应用后生成获取见 创建应用
APP_PRIVATE_KEY开发者私钥,由开发者自己生成获取见 配置密钥
FORMAT参数返回格式,只支持 jsonjson(固定)
CHARSET编码集,支持 GBK/UTF-8开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY支付宝公钥,由支付宝生成获取详见 配置密钥
SIGN_TYPE商户生成签名字符串所使用的签名算法类型,目前支持 RSA2 和 RSA,推荐使用 RSA2RSA2


接下来,就可以用 alipayClient 来调用具体的 API 了。

alipayClient 只需要初始化一次,后续调用不同的 API 都可以使用同一个 alipayClient 对象。


注意:

ISV /开发者可以通过 第三方应用授权 得到商户授权令牌(app_auth_token)作为请求参数传入,实现代商户发起请求的能力。


如果您在调用 API 时出现报错,您可以:

  • 公共错误码 中根据错误码的类型,查找相关错误码及解决方案;
  • 在 小蚂哥 问答页面直接输入您遇到的错误码;
  • 在技术支持 帮助中心 搜索相关错误码,找到解决方案。


第五步:调用接口同步订单信息

小程序订单同步有两种形式:实时同步和异步同步。推荐实时同步用户体验更好,可以同时在“支付助手”消息中露出订单入口,用户可直接复访到小程序查看订单。异步同步的订单不支持在“支付助手”消息中露出订单入口。


实时同步


当用户下单后,商户调用支付接口时可实时同步上传订单信息,同步流程如下图所示:

image.png

订单信息同步

开发者首先通过 ant.merchant.expand.item.open.create 接口上传商品信息,获取 商品ID,再传入 商品ID ant.merchant.expand.item.open.query 接口获取商品 sku_id。最后将查询得到的 sku_id 作为入参传入到支付接口,支付完成后小程序订单同步成功。

(当面付\代扣等支付接口具体见支付API文档)。同时需在支付接口中传入下表中的订单详情页跳转地址和 小程序appid 这两个参数。

参数名称

传参说明

goods_detail#alipay_goods_id

请传入商品 sku_id:获取方式见下方“上传商品信息”章节

extend_params#merchant_order_url

商户小程订单详情页跳转地址:开发者只需在“path”中入参页面地址,系统会自动根据该笔交易对应的 APPID 来拼接链接

business_params#tinyAppId

请传入商户的小程序appid


支付接口中同步订单信息的示例代码如下:


 1{
 2    "biz_content": {
 3        "total_amount": "2",
 4        "scene": "bar_code",
 5        "goods_detail": [
 6            {
 7                "alipay_goods_id": "alipay_goods_id001",
 8                "goods_name": "测试商品",
 9                "quantity": 1,
10                "price": "2"
11            }
12        ],
13        "out_trade_no": "201909030004test",
14        "auth_code": "286809220781188638",
15        "product_code": "FACE_TO_FACE_PAYMENT",
16        "subject": "测试商品",
17        "business_params": {
18            "tinyAppId": "2019041863777777"
19        },
20        "extend_params": {
21            "merchant_order_url": "http://merchant.order.url"
22        }
23    }
24}


alipay.trade.wap.pay / alipay.trade.app.pay 接口中同步订单信息的示例代码如下:


 1{
 2    "biz_content": {
 3        "subject": "测试商品",
 4        "out_trade_no": "201909030004test",
 5        "total_amount": 2,
 6        "timeout_express": "90m",
 7        "product_code": "QUICK_WAP_WAY",
 8        "extend_params": "{\"merchant_order_url\":\"http://order.test.url\"}",
 9        "business_params": "{\"tinyAppId\":\"2019041863777777\"}",
10        "goods_detail": "[{\"alipay_goods_id\":\"alipay_goods_id001\",\"goods_name\":\"测试商品\",\"quantity\":\"1\",\"price\":\"3\"}]"
11    }
12}


订单状态、物流信息等更新时,可通过 alipay.merchant.order.sync 接口来同步更新。

在使用该接口时,一笔成功交易的订单只能同步一次,同步成功的订单若再次同步相同的订单会报错。


异步同步

通过实时同步,商品的素材 ID、商品名称、订单详情 URL同步到订单中心,后续还需接口 alipay.merchant.order.sync 来异步同步商品详情信息,物流信息,订单状态等内容。

当用户订单支付成功后,异步同步订单的接口调用顺序如下图所示:

幻灯片2.PNG

注意:

订单同步需传入素材 ID、商品名称、订单详情 URL,否则订单中心将不展示此笔订单。


幻灯片3.PNG


订单信息同步


开发者通过 alipay.merchant.order.sync 接口,将商品(包含素材 ID)、订单状态、物流单号、订单详情页跳转链接等信息,通过交易号同步到支付宝。同步订单数据的要求请参见下文的《订单明细同步规范》


注意:

若商家接入的不是小程序支付产品,而是使用其他支付产品(如:代扣),回传参数时系统会报出“小程序 id 为空”的错误信息,需要在调用交易接口时入参 business_params,按 "tinyAppId":"xxxxx" 格式传入,appid为小程序ID,入参示例如下:


1biz_content={"product_code":"","seller_id":"","out_trade_no":"","total_amount":"","agreement_params":{"agreement_no":""},"subject":"","business_params":{"tinyAppId":"2017122001010691"}}



订单同步调用接口的请求代码示例如下:


 1{
 2  "out_biz_no": "1234",
 3  "amount": 12.34,
 4  "buyer_id": "2088102165400195",
 5  "seller_id": "2088301176313427",
 6  "partner_id": "2088301176313427",
 7  "trade_no": "2019052322001400191000023731",
 8  "item_order_list": [
 9    {
10      "item_name": "苹果",
11      "quantity": 1,
12      "unit_price": 12.34,
13      "ext_info": [
14        {
15          "ext_key": "image_material_id",
16          "ext_value": "2019061700502200000017592474"
17        }
18      ]
19    }
20  ],
21  "ext_info": [
22    {
23      "ext_key": "merchant_order_status",
24      "ext_value": "MERCHANT_CONFIRMED"
25    },
26    {
27      "ext_key": "merchant_order_link_page",
28      "ext_value": "/pages/order-detail/order-detail?id=1234"
29    }
30  ]
31}


注意:

针对订单同步接口 alipay.merchant.order.sync,需要在主扩展字段和商品扩展字段填入如下参数。


商品信息同步


商品扩展字段可传入商品信息及跳转地址。

1、开发者可在参数  item_order_list 中上传商品信息,必须上传商品名称、单价、数量及商品跳转地址。


参数名称

传参说明

item_order_list

商品信息


2、开发者可在以下参数上传商品跳转地址,同步后用户可在订单详情页点击商品跳转到商户小程序页面,只允许传入 1 次,不允许更新。


参数名称

传参说明

item_order_list# ext_info# merchant_item_link_page

开发者只需在“path”中入参页面地址,系统会自动根据该笔交易对应的 APPID 来拼接商品详情页跳转链接


3、商品信息 item_order_list 可以多次同步覆盖,商品扩展字段 ext_info,本次必须传入素材 ID。如果同步了商品信息,商品扩展字段必须传入素材 ID


参数名称

传参说明

ext_info# image_material_id

素材 ID,存储在 itemcore 数据库中


订单明细跳转


订单详情页的“查看订单明细”跳转到商户小程序订单详情页,跳转信息只允许传入 1 次,不允许更新。

注意:

请商户确保小程序“小程序互相跳转”后台设置为“允许任何小程序跳转”,否则用户在订单详情页无法点击唤起商户小程序。


参数名称

传参说明

ext_info# merchant_order_link_page 

跳转到商户小程序对应的订单详情页链接地址; ext_value 参数请传入 page 后面的值


    幻灯片4.PNG


订单状态同步


当订单状态变更时,可按以下参数来同步更新,用户可在订单中心页面查阅最新订单状态;商户侧订单状态必须满足以下流转状态,如果交易已经退款或关闭,则商户无法再同步订单状态


参数名称

传参说明

ext_info# merchant_order_status 

订单状态

MERCHANT_CONFIRMED:商家已确认

MERCHENT_SERVICING:订单服务中

MERCHANT_DELIVERD:商家发货中

MERCHANT_FINISHED:订单已完成


注意:

商家在同步订单状态时,“订单服务中”和“商家发货中”只能选择其一;同时同步这两种状态会出现报错。


幻灯片5.PNG



物流信息同步


1、当订单状态为已发货时,可回传物流信息,订单中心详情页会展示最新物流进度;后续在 快递详情页 会展示小程序订单信息,引导用户进入商户小程序订单详情页。

2、查看收货人地址 该入口只有回传物流信息且已上传订单明细地址后才会出现,用户点击进入到商户小程序订单详情页。

3、物流信息同步处,开发者需要传入商户订单详情页的链接 merchant_order_link_page 字段,否则是不会显示物流信息。


参数名称

传参说明

logistics_info_list 

物流公司编号和物流单号,物流公司编号点此查看

若查询不到对应的物流公司编号,则说明该物流公司还未和支付宝合作,订单中心无法展示物流状态


演示文稿2.png



上传商品图片


开发者通过 alipay.merchant.item.file.upload 接口上传图片,获取到对应的素材 ID


上传商品信息


  1. 开发者通过 ant.merchant.expand.item.open.create 接口上传商品信息,获取商品ID,再通过ant.merchant.expand.item.open.query 接口获取商品 sku_id。
  2. 上传商品信息ant.merchant.expand.item.open.create 需要传入商品类目ID,商品类目ID可通过 商品类目表 获取。
  3. 调用ant.merchant.expand.item.open.create 接口时,需在“scene”参数入参“APP_ORDER”,该参数标识为小程序商品
  4. ant.merchant.expand.item.open.create 接口中商品详情页链接可在扩展参数“ext_info”中入参页面地址,系统会自动根据对应的 APPID 来拼接跳转链接。

参数名称

传参说明

ext_info# ext_key

ext_key=DETAIL_URL

ext_info# ext_value

ext_value=商品详情页地址,如:page=pages/index/index;系统会自动拼接成地址 alipays://platformapi/startapp?appId=2019xxxxxxxx&page=pages/index/index

  1. 开发者可通过商品相关接口来维护更新商品信息,具体接口见API列表。


订单明细同步规范

订单相关


  • 在首次接入时,开发者需导入最近三个月的”历史订单“数据,导入数据有助于用户查看历史订单数据,同时后续商品可在搜索中获得更多小程序曝光机会。
  • 开发者可以在用户支付完成后,实时同步小程序的交易订单明细,便于用户后续查看交易明细及进度情况。
  • 导入订单必须为用户在小程序内下单支付的订单且回传订单信息包含商品图片、商品名称、订单详情url,否则在订单中心列表页不会展示(系统会自动识别交易来源是否为小程序)。
  • 导入订单明细时,须按支付宝交易号来进行导入数据,订单内的商品信息可更新维护(建议不要多次更新,避免订单内的商品变更对用户体验带来的影响),跳转详情页的参数不允许再次更新,请确保数据准确性再同步。

商品相关


  • 在同步订单明细时,须完整回传该笔交易中用户购买的所有商品明细及商品详情页的跳转地址。
  • 商品图片宽度必须大于 750 px,宽高比建议 4:3 - 1:1 之间。
  • 商品名称建议按以下规范来组合回传:
    • 电商行业:和小程序内展示的商品名称保持一致。
    • 其他行业:若无合适的商品名称,建议可按一些特征来生成商品名称,如:共享充电宝类,商品名称:“租借地点:利星行汽车中心”。

跳转参数


开发者可同步订单详情页和商品详情页的页面地址,用户点击后进入小程序查看交易进度或商品详情等信息,参数规范如下:

  • 开发者只需在“path”中入参页面地址,系统会自动根据该笔交易对应的 APPID 来拼接跳转链接。
  • 用户点击进入小程序时,系统会自动传递访问来源,商户可根据访问来源做一些业务逻辑处理,比如:给通过此渠道过来的复访用户发优惠券;访问来源参数:chInfo=ch_orderCenter
  • 跳转参数同步后不允许更改,请确保数据准确性再同步。


API 列表


此列表包含该产品所涉及的所有接口,点击接口英文名可查看接口的公共请求参数,业务请求参数,返回参数,其他语言请求示例以及错误码等。


接口英文名

接口中文名

alipay.open.auth.token.app 

换取应用授权令牌

alipay.merchant.item.file.upload

商品图片上传接口

alipay.merchant.order.sync

订单数据同步接口

ant.merchant.expand.item.open.create

创建商品接口

ant.merchant.expand.item.open.modify

修改商品接口

ant.merchant.expand.item.open.query

查询商品接口

ant.merchant.expand.item.open.batchquery

批量查询商品接口

ant.merchant.expand.item.open.delete

删除商品接口


如果您在调用 API 时出现报错,您可以:

  • 公共错误码 中根据错误码的类型,查找相关错误码及解决方案;
  • 在 小蚂哥 问答页面直接输入您遇到的错误码;
  • 在技术支持 帮助中心 搜索相关错误码,找到解决方案。