Recurring-代扣/订阅/一键支付接入集成指引

如果您的业务需要代扣/订阅/一键支付等功能，EGMS可以提供API，来帮助你实现这些功能，目前EGMS支持这些功能的支付方式如下（注意：如需使用此功能，请联系 EGMS 进行特别说明，可能涉及新的费用与价格）：

EGMS提供这些能力的实现方式，都是基于EGMS系统的Token能力，因此，您也可以使用统一的Token对接集成流程，来完成这些功能的实现，仅仅只需要在获取到Token后，进行对应的功能流程包装，使用Token发起支付即可。

以下为流程简介，其中提到的接口及字段，可以前往 API规范页面的API specification章节进行查看。

对接Token功能标准流程

Token功能的对接流程，和Payment功能接入的流程极为相似，如果你已经接入过EGMS提供的Payment功能，相信你可以很快得完成Token功能得接入。
前提：向为您提供集成支持的EGMS人员，沟通需接入Token相关能力，他将会为您进行相关功能的配置，并为您分配调用Token功能所需的vaultID等参数；

1. 在计划为代扣/订阅/一键支付等功能申请Token前，建议需要先与顾客进行线上协议签署（一般为列出/弹窗相应条款文件链接及说明，需手动勾选同意，需包含信息收集和使用的隐私政策，包含订阅扣款、退款、取消等条款或政策），同时，收集顾客需要用于代扣/订阅/一键支付等功能的支付方式名称；
2. 调用POST PaymentMethod接口，上送对应的参数（含对应的paymentMethod.recurringProcessingModel，paymentMethod.isFirstCITTxn=true），发起Token申请；
3. EGMS系统在收到请求并处理后，会返回一个应答报文，此时报文根据不同的处理结果，会出现两种情况：
   1. 当报文直接返回了交易已经成功或失败的结果时，result.code不等于S0000 并且 payment.status等于Failed表明Token申请失败，result.code等于S0000 并且 paymentMethod.status等于Success表示Token申请成功，这时你可以存储下来收到的Token信息，用于后续进行支付；
   2. 上述能够直接返回交易成功的场景，一般是在申请国际卡Token的某些情况下，但是更多支付方式，一般会返回一个包含action对象的应答，你需要解析action对象下字段的内容，进行对应的处理，90%以上的支付方式，返回的action.type=redirectUser（国际卡也可为threeDSRedirect），下面以此返回redirectUser为例进行说明，其他返回值后文进一步说明，可根据接入支付方式，按需进行不同action对象的对接处理；
4. 当收到含action对象的应答时，比如action.type=redirectUser，此外还会包含一个跳转链接及跳转方法，此时仅需将此跳转方法和跳转链接，返回给前端页面；
5. 前端页面仅需使用对应的跳转方法，跳转至跳转链接即可；顾客被重定向至跳转链接对应页面，完成后续签约或认证流程；
6. 在顾客完成签约或认证流程后，系统将会发送异步通知至paymentMethod接口提交的webhook处，此时仅需将异步通知的交易结果（paymentMethod.status）对应进行您的后台系统请求状态更新，并保存收到的Token信息，用于后续进行支付即可；除了异步通知外，前端页面在支付流程结束后，也会再次被重定向至PaymentMethod接口提交的returnURL（携带merchantTransID参数）处，建议重定向至returnURL时立即向您的后台系统发送查询以获取支付状态，未获得最终Token申请成功或失败结果前，建议申请状态标志为处理中并向顾客展示；
7. 当然，为了防止因网络原因等造成异步通知未及时送达或其他情况，我们也建议您的后台系统设置轮询机制，以便更好得应对此类情况，查询请求可通过PaymentMethod接口GET方式发起，我们建议的轮询次数和频率如下：总共7次，分别间隔秒数8,16,32,128,512,2048,8192，你也可以适当调整增加次数；如系统已获取到最终支付成功或失败结果则停止轮询；
8. 根据获得的信息，向你的顾客展示对应的支付结果，建议请求失败时也可以将我方返回的失败信息一并展示，便于你的顾客看到失败信息后进行进一步操作；
9. 根据您的代扣/订阅/一键支付等场景需要，在您需要进行扣款的时机，使用获取到的Token，调用POST Payment接口，Payment请求带上获取Token请求返回的recurringReference，发起支付；
   以上即为你要接入EGMS提供的Token功能必须完成的全部内容，当然如果有需要，你也可以参考文档完成其他你需要的Token功能接入，比如：DELETE PaymentMethod用于失效Token。

📘

Tips

如果你的业务场景中不需要先绑卡后续再进行扣款（即一般不存在有免费试用一段时间产品的情况），而是希望客户第一笔交易即可完成绑卡并扣款，且您仅需要国际卡的订阅能力支持，在上述流程的第 2 步中，您可以直接调用 POST Payment 接口，仅需要在调用接口时上送如下参数：paymentMethod.card.tokenize = true 并设置paymentMethod.card.userReference字段，另建议主动设置allowAuthentication = true ，这样第一笔交易就可以完成绑卡并扣款，也可以获得 Token 和recurringReference 用于后续的扣款。（再次提醒：此类方式仅适用于国际卡的订阅，钱包的订阅暂不支持一笔Payment 交易直接完成绑卡和扣款）

代扣流程包装及建议

1. 代扣发起前：如上述步骤中第1步描述，建议需要先进行线上协议签署（一般为列出/弹窗相应条款文件链接及说明，需手动勾选同意，需包含信息收集和使用的隐私政策，包含订阅扣款、退款、取消等条款或政策）；
2. 获取Token时设置paymentMethod.recurringProcessingModel=Unscheduled；
3. 签约获取Token后：

• 需要提供一个线上可简单访问并发起取消代扣/订阅的入口；
• 需要提供查看代扣/订阅扣款时间或间隔展示的途径；
• 在以下情况发生时，需要至少提前7天，通过邮件或其他约定的沟通方式，通知持卡人：
  • 试用期/促销期即将结束。在通知内容中，需要包含：订阅交易扣款金额、扣款时间、取消订阅的入口链接或其他比较容易进行订阅取消的线上或短信的取消方式；
  • 对于发生在欧洲区域或持卡人发卡行为欧洲地区的交易，本次订阅扣款距离上一次订阅扣款时间间隔超过了6个月，也需要按上述描述通知；
  • 对于发生在欧洲区域或持卡人发卡行为欧洲地区的交易，如果订阅协议发生变更，包括订阅扣款金额、订阅扣款时间、或者订阅协议内的其他条款变化时，也需要按上述描述通知；

一键支付包装及建议

一键支付一般每次付款还是由客户发起，但是因为是通过Token来最终完成支付，所以不需要进行中间授权、确认等页面跳转和操作，支付效率有了非常大提升；在获取token时，需上送CVV，并设置paymentMethod.recurringProcessingModel='CardOnFile'以及paymentMethod.ifFirstCITTxn=true。
包装实现上，当客户来到收银台页面，选择绑定Token时使用的已绑定的支付方式进行支付时，上送paymentMethod.recurringProcessingModel="CardOnFile"且paymentMethod.isSubsequentTxn=true，有助于提升成功率，CVV可不上送。

订阅流程包装及建议

订阅一般特指固定金额固定频率的循环代扣场景，本质也是一种代扣场景，需在为订阅交易申请Token前明确展示相关的费用价格情况，并且设置paymentMethod.recurringProcessingModel='Subscription'以及paymentMethod.ifFirstCITTxn=true，并且，订阅发起的后续交易，需提交该客户签约的订阅协议获取Token的订阅关联号（获取Token请求返回的recurringReference），以便进行同一订阅交易关联，其他相关建议跟代扣一致，同时，需您自身系统控制好使用Token发起扣款的时间；订阅页面可参考设计样例如下：