API集成简版指引

通过本文档，你可以轻松完成EGMS提供的线上支付能力的集成。

EGMS 业务合作总体流程

总体支付流程介绍

EGMS对所有的支付方式的支付调用，都封装成了一致的处理流程，所以你可以统一使用如下流程，调用对应的接口来完成EGMS提供的所有支付方式的支付流程集成：

1. 在您的收银台页面，展示出你希望调用的支付方式供顾客选择，顾客选择该支付方式并收集好对应支付方式的支付数据后，将支付请求提交至您的后台系统；

2. 您的后台系统参考Payment接口POST方式的接口规范，使用EGMS分配的SID及对应的密钥参数（每个网站/APP会分配对应的不同的参数），组装报文并调用该接口，将支付请求提交至EGMS系统；

3. EGMS系统在收到请求并处理后，会返回一个应答报文，此时报文根据不同的处理结果，会出现两种情况：

   1. 当报文直接返回了交易已经成功或失败的结果时，result.code等于S0000 并且 payment.status等于Captured或Authorised表示交易/授权已经成功，payment.status等于Pending且无action对象表示交易处理中，可以发起一笔查询获取支付结果，result.code不等于S0000表明交易已经失败，这时你可以直接向你的顾客展示对应的支付结果；
   2. 上述能够直接返回交易成功的场景，一般是在国际卡支付的某些情况下，但是更多支付方式，一般会返回一个包含action对象的应答，你需要解析action对象下字段的内容，进行对应的处理，90%以上的支付方式，返回的action.type=redirectUser，下面以此返回为例进行说明，其他返回值后文进一步说明，可根据接入支付方式，按需进行不同action对象的对接处理；

4. 当收到含action对象的应答时，比如action.type=redirectUser，此外还会包含一个跳转链接及跳转方法，此时仅需将此跳转方法和跳转链接，返回给前端页面；

5. 前端页面仅需使用对应的跳转方法，跳转至跳转链接即可；顾客被重定向至跳转链接对应页面，完成后续支付流程；

6. 在顾客完成/结束支付流程后，系统将会发送异步通知至Payment接口提交的webhook处，此时仅需将异步通知的交易结果（payment.status）对应进行您的后台系统支付状态更新即可；除了异步通知外，前端页面在支付流程结束后，也会再次被重定向至Payment接口提交的returnURL（携带merchantTransID参数）处，建议重定向至returnURL时立即向您的后台系统发送查询以获取支付状态，未获得最终支付成功或失败结果前，建议订单状态标志为支付处理中并向顾客展示；

7. 当然，为了防止因网络原因等造成异步通知未及时送达或其他情况，我们也建议您的后台系统设置轮询机制，以便更好得应对此类情况，查询请求可通过Payment接口GET方式发起，我们建议的轮询次数和频率如下：总共7次，分别间隔秒数8,16,32,128,512,2048,8192，你也可以适当调整增加次数；如系统已获取到最终支付成功或失败结果则停止轮询；

8. 根据获得的信息，向你的顾客展示对应的支付结果，建议支付失败时也可以将我方返回的失败信息一并展示，便于你的顾客看到失败信息后进行进一步操作；

   以上即为你要接入EGMS提供的线上支付必须完成的全部内容，因为我们提供商户平台供你来完成退款、对账等其他内容，当然如果有需要，你也可以参考文档完成其他你需要的功能接入。也就是说集成EGMS API，您最少进行对接POST Payment、GET Payment、异步通知三个接口即可。

API规范文档重点章节

API规范文档重点章节
API规范集成了很多接口和功能，所以内容比较多，建议可以当成字典在需要时翻阅即可，无需全文阅读后再进行集成开发，以下为相应重点内容所在章节，接入集成时对以下指定内容进行对应查阅即可：

• API基本规则、签名及验签说明请查询章节--“6 API Rule”
• POST Payment接口规范请查阅章节--“7.4.3.1 POST Payment”
• GET Payment接口规范请查阅章节--“7.4.3.3 GET Payment”
• 支付异步通知接口规范请查阅章节--“7.9.1.2 Notification for Payment”
  附完整API规范文档供查阅，下文展示了一个典型的POST Payment请求报文，供快速参考，另附postman请求样例，内含各支付方式的请求样例，你可以尝试直接通过postman发起请求或参照其中的样例进行代码开发，这样可能会进一步帮忙你更好更快的完成集成。

完整 API 规范及 postman 请求样例可前往https://developer.evonetonline.com/docs/merchant-services-api 进行API specification和Postman JS的在线查看或下载

不同支付方式对应的action及其他要点说明

可前往 不同支付方式集成指引进行查看

文件集成指引【可选】

文件获取方式

EGMS默认提供portal手工获取文件的方式，可通过登录portal，前往Report - Report List菜单，选择并下载获取文件；EGMS目前还提供SFTP的方式进行文件获取，如您需要SFTP的方式，请联系EGMS对接人员进行申请开通；EGMS支持人员将会在申请开通后，提供您专属的用于访问SFTP的地址、账号、密钥等参数。

文件规范

文件规范如下，请仔细约定规范，以便能够正确处理文件，另附文件样例便于理解和接入集成：

文件规范：

文件样例：

Activity Detail 联机交易流水明细文件

Settlement Detail 清算交易流水明细文件

Miscellaneous Detail 清算手工交易流水明细 文件

集成处理建议

规范中提及的文件，可根据您的需求，选择性进行接入；

• 关于文件获取时间建议：因文件处理时间一般在东八区时间上午10-12点，如无特殊需要，建议12点或之后进行获取；如希望提前获取，建议在11点及之后获取，无论如何，为防止特殊情况发生，建议设置可以手动重新获取文件的功能。
• 关于对接哪个层级的文件：对于单个商户而言，看是否需要将下属所有门店/网站合并在同一文件中进行处理，如需合并则对接商户层级文件即可；如需按门店/网站拆分，则对接门店层级文件；对于PF机构客户而言，同样看是否需要将所有交易合并同一文件成立，如需合并则选择集团层级，并且一般建议选择集团层级；注意不同层级的文件在字段上会稍有不同，具体请查看规范。
• 对于File-01-Activity Detail 联机交易流水明细文件，此文件为不包含清算信息的交易流水文件并且包含成功与失败状态的交易，一般用于双方系统间状态同步的初步勾兑，如无特殊需求可不进行对接，直接使用包含清算信息的流水文件进行勾兑及处理。
• 对于File-02-Settlement Detail 清算交易流水明细文件和File-03-Miscellaneous Detail 清算手工交易流水明细文件，这两个文件为包含清算信息的明细文件，一般如需进行文件对接，建议至少对接File-02-Settlement Detail 清算交易流水明细文件，对于该文件对接有如下建议：
  1. 提取您自有系统侧待勾兑交易成功数据，如接口发起交易上送订单号（接口字段为merchantTransID）时，已确保订单号全局唯一，则可使用商户订单号字段-Merchant Txn ID作为勾兑主键，与此文件中的数据进行数据勾兑，如上送时未保证其全局唯一性，建议使用门店号+Merchant Txn ID作为勾兑主键进行数据勾兑；
  2. 对于勾兑后您方系统数据中，为您方系统侧多的数据，建议将这部分交易纳入后续的勾兑数据，不立即报警并纳入人工处理环节，在部分交易经过第N天勾兑后（N数值一般建议为5天），仍然为商户侧多数据，则纳入人工处理环节，与业务部门及EVONET沟通确定原因；为了避免一些因文件处理、补发或延迟导致的异常，建议第M天后（M一般建议为8天），再将此部分交易报警人工确认原因丢弃，不再纳入后续的勾兑数据；
  3. 对于勾兑后，为您方系统侧少数据，建议可以采取与上述一样的处理流程，亦可以采取比上述时间更快的时间（减少3天）纳入人工处理环节，与业务部门及EVONET沟通确认原因；
  4. 对于勾兑平数据及勾兑后业务逻辑处理，可根据您方业务需要，自行处理；
  5. 其他可进行勾兑或处理的关键字段有：Merchant Txn Amt（交易金额）、Merchant Sttl Amt（清算金额，扣除手续费前）、MDR Amount（手续费）、Net Merchant Sttl Amt（清算净额），还有其他如需要字段，可查看规范视需要进行处理。
• 对于File-03-Miscellaneous Detail 清算手工交易流水明细文件，该文件为手工及特殊类交易文件，比如拒付或者手工扣款类，这部分交易为非您方系统发起的交易，所以无需勾兑，如需要处理，则直接进行对应记录的解析，获取到对应的记录并进行系统处理即可。