应用场景

在需要校验用户身份的场景，比如：是学校学生或教职工才允许用餐，校外人员不能用餐，这种情况下需要先判断用户是否符合身份条件（通过付款码解码接口实现），校验通过才能继续支付否则提示身份校验不通过无法支付。

名词解释

核身付款码方案介绍

1. 操作流程：

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

2、整体业务流程

分两个阶段，学生支付宝账户uid与一卡通账户绑定阶段、学生支付阶段。

（一）、学生支付宝账户uid与一卡通账户绑定阶段

说明:

1).学生访问ISV小程序，通过小程序用户授权，isv可获取并保存用户uid。

2).isv获取uid后，对学生进行身份认证，将uid与学生身份绑定。

3).通知学生认证完成，可以进行线下核身支付。

（二）、学生支付。

说明：

1. 红外扫码枪，扫描钱包的“付款码”，识别出码信息；
2. 通过“通用当面付二阶段接口”获取用户uid与系统开卡时记录的uid做校验。对付款者身份识别。
3. 校验通过后，通过当面付的条码付款接口“alipay.trade.pay”发起支付请求。校验不通过，提示用户通过isv小程序做用户授权，在支付。

技术方案评估

      本方案在集成过程中，主要是二阶段接口调用。交易接口传参都一致。二阶段接口有三种方式：

      集成方式一、小程序授权方式，调用当面付二阶段接口

目前一些ISV，有通过开放平台有对接过当面付的标准产品，也有ISV实现 核身付款码支付的能力，还有的合作伙伴没有接入过支付宝开放平台产品，三种对接现状给出对应引导。

1.没有对接过支付宝当面付、小程序的卡商或isv，对接核身付款码方案，请阅读“开发前准备”、“开始集成”进行对接。

2.已经对接过当面付的isv，在对接核身付款码方案，需开发

• 如果之前没有接入支付宝IOT平台，需要集成硬件IOT对接
• 开发支付宝小程序，小程序授权
• 当面付二阶段接口
• 交易接口。
• 请阅读“开发前准备”、并按照本文档中“开始集成”中的IOT对接、开放平台接口对接中的第2、3、4、5步对接。

     集成方式二、使用认证组件方式，调用当面付二阶段接口

         调用认证组件后，支付宝将认证数据发送到isv的认证网关上，网关认证通过后，学生认证完成，调用二阶段接口。

1.通过支付宝中心认证入口或者ISV小程序调用支付宝认证组件。认证组件接入指引

2.身份认证组件对应的服务端认证接口，参见一卡通认证绑定.pdf中2.认证。

   此接口为SPI接口，需要isv按照接口规范开发好后，发布，上传到调用接口的appid的应用网关处。应用网关配置。

     集成方式三、使用会员卡开卡链接方式，调用当面付二阶段接口。

1.集成电子校园卡

2.调用二阶段接口

     另外、之前已经对接过老的二阶段接口目前可以继续使用，但建议改造成新的二阶段接口。

已经接入老的付款码解码和当面付产品的isv，可继续使用，无需改造。

开发前准备

• 签约及配置准备

1. 开通当面付接口权限，由服务商代学校完成签约。
2. ISV创建一个小程序应用（创建应用）、添加“获取会员基础信息”功能包、调用小程序用户授权，获取用户uid。
3. ISV第三方应用授权appid（创建应用），申请通用当面付二阶段接口由支付宝业务同学挂包。
4. 登录开放平台，配置应用环境，包括应用功能，RSA2的公钥、授权回调地址等。

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

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

      5. 下载服务端sdk

开始集成

以第三方应用授权模式调用：开发前请仔细阅读

一、设备对接：

   1.IOT对接申请：

    isv或者支付宝业务同学，发邮件iot_campus@service.alipay.com 申请对接需求。iot解决方案同学收到后承接IOT对接。IOT接入流程，参见《校园行业IOT接入SOP指南 1.0 beta.pdf》

   2.IOT平台对接及交易接口参数

  IOT平台接入有云端管控API接口方式和IOTSDK方式，由业务根据实际情况统一协调。不同方案，交易接口传参要求不同。

    1).云端管控API接口方式接入指南、IOT云端设备交易对接流程

    2).IOTSDK方式分厂商集成与isv集成。厂商集成指南、ISV开发手册

    3). IOT交易传参说明及iot加签说明，参见《IOT平台接入交易接口使用说明》

二、开放平台接口对接：

1.第三方应用授权接入：

  服务商开发第三方应用授权，通过授权链接或者授权二维码提供给学校，学校签约当面付完成后，登陆签约支付宝账户给服务商授权。服务商获取授权app_auth_token。。

 1).第三方应用授权接入指南：https://docs.open.alipay.com/20160728150111277227/intro

 2).授权app_auth_token服务商本地要保存好，第三方授权调用模式下，需要通过交易接口请求给支付宝，必传。

2.ISV开发支付宝小程序：参见小程序文档

学生在小程里序完成学生信息与支付宝信息绑定（学生可以通过此小程序填写一卡通及一卡通密码，将一卡通与支付宝uid建立绑定关系），ISV在服务端落一卡通与支付宝uid的绑定关系，并对uid打学生标。

注：学生打开小程序，需要做用户授权进行授权。

3.小程序用户授权接入：

学生授权ISV,获取用户uid；小程序授权的scope传auth_paycode_getuid ；授权后获取authCode，然后调用alipay.system.oauth.token(换取授权访问令牌)，接口中code参数传入小程序获取到的authcode参数，获取用户的uid

 1).小程序授权接入指南

4.通用当面付二阶段接口：接入文档

1).线下消费时，需要核实身份，此接口为学校核对学生身份提供uid，如果核对身份不是学生/教工，可以不调用支付接口，在机具上展示对应的文案提示。

alipay.user.twostage.common.use （通用当面付二阶段接口），参数说明：

• 通用当面付二阶段接口中dynamic_id(商户扫描用户的付款码值)。
• 通用当面付二阶段接口中sence_no（外部业务号），用于标识这笔解码请求，每次请求的sence_no必须不一样，对于同一个码的重复解码请求，sence_no必须与上一次保持一致。当与支付接口(alipay.trade.pay)一并使用时，交易接口入参extend_params/DYNAMIC_TOKEN_OUT_BIZ_NO赋值一致。即：extend_params":{"DYNAMIC_TOKEN_OUT_BIZ_NO":"sence_no的值"}
• 通用当面付二阶段接口中pay_pid（商家进行二阶段支付的pid）用户给商家授权时对应的商家支付宝账户pid。
• 通用当面付二阶段接口与支付接口（alipay.trade.pay）配套使用时，需注意调用两个接口的appid需要保持一致，否则支付接口会报付款码无效（PAYMENT_AUTH_CODE_INVALID）错误。
• 之前有合作伙伴使用付款码解码接口（包含新版和老版），目前可以使用，但建议对接通用当面付二阶段接口（最新版）请移步接口文档

5.当面付接入：直连接入与间联接入，传参有不同。此处主要讲当面付直连接入传参。

   1).直连接入当面付：当面付接入指南。对接时，请先阅读当面付接入指南，接入必读，最贱实践。业务逻辑建议按照接入指南对接。

    参数说明：

1. 需在alipay.trade.pay(统一收单交易支付接口)中，增加下面参数作为返佣标识。extend_params/sys_service_provider_id参数中传入isv签约返佣协议账户的pid（必传）。
2. alipay.trade.pay接口的extend_params属性中必须设置DYNAMIC_TOKEN_OUT_BIZ_NO，取值必须与alipay.user.twostage.common.use接口sence_no参数赋值保持一致。即：extend_params":{"DYNAMIC_TOKEN_OUT_BIZ_NO":"sence_no的值"}
3. IOT交易传参。

• SDK方式接入IOT:  需在alipay.trade.pay接口中增加一个与out_trade_no平级的参数terminal_params，取值为“业务签名”以json字符串传递。该参数取值需要isv与机具厂商沟通确认如何获取（与智能机具平台对接的机具该参数根据业务需求确定是否传入此参数）。

terminal_params参数，取值为IOTSDK生成的业务签名值。IOT加签方法：https://alipay.open.taobao.com/docs/doc.htm?articleId=109629&docType=1#s1。签名样例：

        注意：由于交易报文协议为JSON格式，在构造terminal_params属性时，必须以字符串形式，因此，务必注意子json字符串的表示格式（需要转义）。

• 云端API方式接入IOT:需在alipay.trade.pay接口中需传入terminal_id：支付宝对该设备分配的统一设备IDbizTid；

  示例："terminal_id":"IOT;01010je01z5XGHTyxKAjxJQfavrCKH3CwgM2tLwrYurnyHLmOHAICM4"。bizTid获取请参考 IOT设备云端接入集成指南 第4节，通过IoT设备信息查询API查询获取。

•  alipay.trade.pay (统一收单交易支付接口)接口中增加IOT扩展参数。  此参数与IOT接入方式无关，必传参数。

   *2.0 接口，从接口参数上传入该参数：business_params; json 格式：key 为：iot_pay_action

   * 对应value 定义如下： iot_pay_action: online_face_pay - 在线刷脸支付、local_face_pay - 本地刷脸支付、nfc_pay - 刷卡支付、bar_pay - 扫码支付 

验收上线

验收文档由支持对接同学提供。核身付款码验收checklist

相关文档

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

1. 当面付接入指南
2. 当面付API列表
3. 通用当面付二阶段接口（推荐最新版，支持第三方应用模式调用，需支付宝业务经理签约）
4. 当面付组件，可参考。使用机具支付组件开发，可大大降低开发者开发工作量，详见组件说明文档。
5. 网关校验规则

资金方案

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

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

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

     在直接收款到商户支付宝账户的基础上，同时添加分润限制集合，alipay.trade.pay交易成功后，可以通过alipay.trade.order.settle(统一收单交易结算接口)实现分润

    接口中royalty_parameters传入分润参数，分润参数中收款账户填写学校收取管理费的账户。分润格式参考文档：

系统对账

获取有如下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左右（根据业务需要自行确定轮训时间），如果超时仍未返回付款结果直接调用撤销接口关闭当前交易，重新创建交易重新支付。

4、Q：错误码信息查询？

    A: 公共错误码

5、Q:网关通信协议规范

    A:https://docs.alipay.com/mini/openability/sdo5z5

FAQ