准备工作

了解团餐支付接入指南之前，建议先完整阅读智能机具平台整体解决方案。了解整体业务流程、机具厂商与ISV的职责以及各方准备工作。

名词解释

1、团餐支付介绍

团餐支付是指一群相对固定的人在固定场所用餐支付。通过食堂机具扫码完成付款，方便快捷，大大提升付款速度。

2、产品实现逻辑

无需身份校验即可付款

说明：

1. 红外扫码枪，扫描钱包的“付款码”，识别出码信息；
2. 通过当面付的条码付款接口“alipay.trade.pay”发起支付请求。

开发前的准备工作

1. 开通当面付接口权限，由服务商代学校完成签约。
2. 开放平台--开发者中心--应用查看--添加“开通解码接口”、“用户信息获取”功能包，并自助签约“当面付付款码解码”。如需获取用户身份证号等信息请通过钉钉审批流提交申请，申请方式详见对接手册”的步骤二。
3. ISV创建门店、绑定门店操作，详见ISV服务商机具申请操作手册。
4. 登录开放平台，配置应用环境，包括应用功能，RSA2的公钥、授权回调地址等。

• 如果调用接口使用校方的账号，那么校方同样需要入驻支付宝的开放平台，创建应用，配置环境并添加应用功能，成为“自研开发者”。

• 如果ISV采用“第三方应用授权”的方式调用接口，那么ISV的应用同样需要配置应用环境。

• 应用添加功能包括：“当面付”、“当面付付款码解码功能”等，根据业务需要选择。如图:

组件使用说明

使用机具支付组件开发，可大大降低开发者开发工作量，详见组件说明文档。

开始开发

开发前请仔细阅读接口开发文档及相关参数说明。

1. 当面付接入指南
2. 当面付API列表

返佣参数说明：（已接入团餐方案的isv请仔细核对以下返佣参数，如缺少以下参数要按需增加对应参数）

• 未接入IOT

       alipay.trade.pay (统一收单交易支付接口)接口中传参：

       1).extend_params/sys_service_provider_id：传isv签约返佣协议账户的pid（必传）；

       2).alipay_store_id参数，该参数取值为在开放平台中创建门店时生成的“门店ID”。(如果有创建门店要求，需要必传入。以门店维度下面的机具返佣有关）。

• IOTSDK接入方式

       alipay.trade.pay (统一收单交易支付接口)接口中传参：

       1).extend_params/sys_service_provider_id：传isv签约返佣协议账户的pid（必传）；

       2).terminal_params：机具签名（IOTSDK交易加签结果，参照样例）；

       3).alipay_store_id参数，该参数取值为在开放平台中创建门店时生成的“门店ID”。(如果有创建门店要求，需要必传入。以门店维度下面的机具返佣有关）。

       4).total_amount： 订单金额，交易加签时涉及到金额加签，需要传入此金额。加签金额的格式、金额一定要保持一致。

       *terminal_params参数，取值为IOTSDK生成的业务签名值。签名样例：

 {"terminalType":"IOT","signature":"ERKDmm3fhGCvZZP0ob5gHUiTuTaFbB5gjjYBYxdOVwezN+sSJdV+uJy4kegYC6RQDzOLx/vbLYPoZTzxPXsVAFZgCg==","apdidToken":"iBfdgYKtgBObNOOybNHkaItG2EQkY3bovzvKDqtyWKVQ9tfvZAEAAA==","hardToken":"0601469C6568AEB7BA92FCC21DF8C766CC8A78A5BF874FC509A2D262B8B5FB9E35FF","time":"1533061133","bizCode":"11000100020002200020","bizTid":"01010020015XmMUS5BmWl39qqatmTLukjswaEaSYJADU2EQ2kb3AjcY","signedKeys":"authCode,totalAmount,apdidToken,hardToken,time,bizCode,bizTid"} 

• 注意：由于交易报文协议为JSON格式，在构造terminal_params属性时，必须以字符串形式，因此，务必注意子json字符串的表示格式（需要转义）。
• IOT SDK加签文档：https://alipay.open.taobao.com/docs/doc.htm?docType=1&articleId=108944

 门店创建如下图：

https://openapi.alipay.com/gateway.do?timestamp=2018-01-01 08:08:08&method=alipay.trade.pay&app_id=5158&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&biz_content=
 {
    "out_trade_no":"20150320010101001",
    "scene":"bar_code",
    "auth_code":"28763443825664394",
    "product_code":"FACE_TO_FACE_PAYMENT",
    "subject”:”机具支付”,
    "total_amount":88.88,    
    "alipay_store_id":"test_store_id",   
    "terminal_params":"{\"signature\":\"DtIEDsLxxHr5P61nDq/QLpWr1mTsaXLyLPjI7PQOr10B\",\"credential\":\"2898999992378080044:1408661770:3fCBzPYttp8rRwImpS1TPQPls0mtDLIUjQCVErBrjpOsbrQAYgEAAA==\",\"terminalType\":\"IOT\"}";  
"extend_params":{"sys_service_provider_id":"2088511833207846"} 
}

代码请求示例：

/**
 * 测试当面付条码支付接口，带业务签名信息
 */
@Test
public void testAlipayTradePay() throws Exception {
    AlipayTradePayModel model = new AlipayTradePayModel();
    model.setAuthCode("28989999994317374740");  // 付款码信息
    model.setOutTradeNo("pay" + System.currentTimeMillis());  // 订单号，在ISV系统保证唯一
    model.setScene("bar_code");     // 固定值
    model.setSubject("一姜测试机具支付002");  // 订单标题，会展示在收银台和账单页
    model.setBody("购买矿泉水2瓶");   // 订单详情
    model.setTimeoutExpress("1m");  // 订单自动关闭时间设置为1分钟
    model.setTotalAmount("0.01");   // 订单金额
    model.setAlipayStoreId("test_store_id");       // 门店id，通过开放平台创建的门店id
    model.setTerminalId("test_terminal_id"); // 终端号，ISV可自定义管理
     
    // 通过该字段传递业务签名，业务签名通过机具提供的接口生成。
    model.setTerminalParams("{\"signature\":\"DtIEDsLxxHr5P61nDq/QLpWr1mTsaXLyLPjI7PQOr10B\",\"credential\":\"2898999992378080044:1408661770:3fCBzPYttp8rRwImpS1TPQPls0mtDLIUjQCVErBrjpOsbrQAYgEAAA==\",\"terminalType\":\"IOT\"}");
     
    ExtendParams extendParams = new ExtendParams();
    extendParams.setSysServiceProviderId("2088100020003000");  // 填写系统商的PID
    model.setExtendParams(extendParams);
 
    AlipayTradePayRequest request = new AlipayTradePayRequest();
    request.setBizModel(model);
 
    AlipayTradePayResponse response = client.execute(request);
    logger.info("response body: {}", response.getBody());
}

资金方案

1、直接收款到支付宝账户场景

      isv通过第三方应用授权模式替学校调用当面付付款接口，学校签约账户直接收款。

2、直接收款到商户账户场景

     商户向支付宝客户经理申请添加收款限制集合，isv根据交易服务提供方来决定传递哪个账户收款，通过seller_id传递不同收款账户pid实现。

3、直接收款到商户账户，同时学校从交易中抽取管理费场景

     在方案1、2基础上完成直接收款到商户支付宝账户，同时添加分润限制集合，alipay.trade.pay接口中传入 royalty_info分润参数，分润参数中收款账户填写学校收取管理费的账户。分润格式参考样例：

"royalty_info": {
	"royalty_detail_infos": [{
		"amount": 1,
		"trans_in": "2088202415071394",   //润款转入账户
		"trans_out": "2088911212445410",  //分润转出账户
		"trans_out_type": "userId"        //分润类型
	}],
	"royalty_type": "ROYALTY"             //固定值
},

系统对账

获取有如下3种方式，请根据业务需要选择。如有系统对账需求须通过前2种方式实现。
1、接口对账：适用于通过系统自动对账的商户。调用查询账单接口(alipay.data.dataservice.bill.downloadurl.query下载对账单，ISV系统内完成自动对账。签约当面付产品默认开通账单下载地址接口权限。可以获取到业务账单和账务账单。

2、sftp对账：适用于通过系统自动对账的商户。

新申请sftp账户需商户提供以下信息，并由支付宝BD提交申请配置。账单默认生成时间为次日早上8点至12点之间随机生成。

      1).需生成账单的Partner ID;

      2).需要账单类型：分别为账务账单和业务账单选其一，也可以都选。

      3).获取对账单的商户服务器外网ip（支付宝会将ip加入白名单，只有白名单内的服务器才可访问sftp服务器下载账单）。

配置申请成功后会给商户分配对应的sftp账户和密码，由BD输出给到商户，商户通过账户密码访问支付宝sftp服务器获取账单。sftp地址为：sftp.alipay.com（旧地址）、antsftp.alipay.com（新地址） 端口：22。

3、支付宝站内下载账单：签约账户登录www.alipay.com，到对账--账单下载中下载日账单。

常见问题 

1、Q:付款请求发出后未收到支付成功通知如何处理？ 
A:未收到付款结果通知可以调用查询接口查询订单状态，食堂排队付款场景下一般轮训时间5s左右（根据业务需要自行确定轮训时间），如果超时仍未返回付款结果直接调用撤销接口关闭当前交易，重新创建交易重新支付。

2、Q：机具异常离线状态下如何收款？

     A：服务商开发付款收银页面生成二维码在机具上贴码，扫码后跳转到服务商开发的付款页面，输入金额点击确认支付，通过当面付交易创建（alipay.trade.create）接口，js唤起收银台完成收款，方案详见：https://docs.open.alipay.com/common/105591。

3、Q:付款请求发出后未收到支付成功通知如何处理？ 
     A:未收到付款结果通知可以调用查询接口查询订单状态，食堂排队付款场景下一般轮训时间5s左右（根据业务需要自行确定轮训时间），如果超时仍未返回付款结果直接调用撤销接口关闭当前交易，重新创建交易重新支付。 

FAQ