Day16 - 铁人付外挂前置作业 (ㄧ) - 串接文件

不管是哪一家软件公司或是金物流厂商,只要他们有提供 API 介面来服务外部网站,通常一定会有串接文件可让开发者参考,串接文件就像是 API 使用说明书,让开发者可以知道该怎麽与手边的系统进行整合。

串接文件通常有分线上版与离线版,离线版就是会拿到一份 PDF 或 Word 档,台湾金流业者多半是这种类型,可以直接在官网下载。另外有些厂商可能有某种商业考量,会需要申请并审核通过後才能取得他们的串接文件。

还有的是在官网找不到文件下载的连结,只能透过业务窗口取得,总之不管文件的形式为何,当我们的客户说想要串接金流或是其他的服务时,第一个首要之务就是取得串接文件,有串接文件我们才能评估工作项目。

其次,如果拿到的文件是离线档案,务必要确认是否为最新版本,我就曾经发生过拿到旧的版本结果一直无法顺利串接的情况,正常情况下厂商的 API 介面只会新增不会修改或删除既有的方法,但还是让我遇到了,因此一定要跟客户确认文件是否为最新版本。

有了文件之後还需要取得客户的使用名称与密钥,如果以金流为例,通常会有商家代号以及串接密钥,前者是金流商辨识客户的依据,後者是拿来算出加密演算法的参数之一,而金流商会用这个密钥算出来的值来作为请求付款的身份验证,所以取得与客户身份相关的串接资料是必要的。

正常情况下,厂商提供的 API 会有分正式与测试环境,通常是用请求路径来区分,如果是接金流的话,还会有测试卡号来验证刷卡是否正常运作,而不用掏自己的信用卡,但也遇过没有测试卡号只能用一元订单来测试的厂商,这些资讯在串接前最好都能请客户先跟厂商确认,不然串接到一半才发现这些资讯有误的话,会浪费很多时间在进行除错。

金流串接文件注意重点

接下来,当我们拿到文件後,必须先理解这家厂商的 API 逻辑,理解後我们才能比较准确的进行任务拆解与工时评估,通常我会注意文件的以下几个重点:

流程怎麽走?

根据流程图可以先大概掌握要在什麽时间点把订单资料送给金流商、在哪个阶段做授权验证以及接收回传资料的时机,台湾的第三方金流多半是订单传送时同时做授权验证,验证成功後交给金流商跳转到付款页,现在市面上也有陆续出现直接在客户网站内完成结帐的服务,只要看流程图我们大概就可以知道客户网站跟金流厂商之间的资料是如何传送的。

验证怎麽做?

这是金流商用来验证从客户传过去的资料是否为客户网站,不同的厂商名称可能不太一样,有叫检查码的,还有检核码、加密法、签名演算法一堆名称,文件会说明该如何将传送资料做大小写排序、经过组合客户密钥、URL Encode、产生杂凑值、转换大小写等一堆折腾人的过程,比较贴心的厂商会提供程序范例,我会把这范例写成一个静态方法,之後在做验证时就可以重复利用。

要传的参数有哪些?

通常要传给金流商的参数很多,但不外乎就是订单的相关资料,我会注意有没有比较特别的栏位,也就是 WooCommerce API 无法一行程序拿到的资料,这种会增加开发时数的栏位要及早发现,还有就是设定付款方式的栏位该如何使用、资料类型为何、有没有什麽限制,尤其是限制的部分,会需要在资料传送前先做检核,像是姓名长度、电话号码的格式等等,这些都需要计入工作项目之中。

回传的参数有哪些?

根据客户的商业情境不同,可能会需要取得刷卡的後四码或是交易流水号以方便客户对帐,所以要预先知道能取得的回传资料有哪些,才能把订单栏位建立好并写入资料库。

交易失败会显示什麽?

串接文件通常会有状态码对应讯息的表格,用来说明当 API 回应某些状态码时代表的是什麽意思,我会特别关注交易失败的状态码,像是卡号错误、信用卡验证码错误等等的讯息,以便在接受回传资讯时可以把交易失败的例外状况考虑进去,再根据状态码来显示订单交易失败的原因,这样当出问题时才能进行追踪。

铁人付金流外挂开发任务拆解

看完文件後,对於该如何串接这个厂商的 API 心里大概就会有个底,接下来我把开发任务拆解为四大类:

前置作业

这个阶段会包含三个工作,分别是确认完成验收标准、金流串接相关资料交付确认以及开发环境与程序码部署配置。首先要跟客户确认需要串接的付款方式有哪些,以及采用使用者故事来描述顾客结帐流程以及管理者的操作行为。通常金流商提供的付款方式很多种,每种的使用费用不太一样,客户会因成本考量有可能全接或是只接部分的付款方式。

另外还需确认付款的介面设计、顾客完成後的显示栏位以及後台订单对帐资讯,因为我们已经先行阅读过文件了,所以可以跟客户主动建议哪些资料可以显示以采取对应的作法。

其次的金流串接相关资料交付最好在开工前取得,并且确保是正确的资料,避免串接到一半发生问题,而这部分的工时就是遇到这种状况的缓冲。

最後的开发环境与程序码部署配置在後续的文章会提及,主要就是建立开发 WooCommerce 的环境配置。

WooCommerce 设定介面开发

前台的介面是在 WooCommerce 结帐页增加金流选项,以及会根据不同的付款方式显示不同的介面,像是分期付款的选择期数,後台的介面是让客户可以自行输入商代代号、密钥以及切换正式或测试环境的设定,後台的介面事实上不一定需要,但有的话可以省下日後修改程序的时间,而且如果未来要发行此外挂的话,设定介面是必须的项目。

金流 API 串接

这部分包含了串接文件中的实作,像是加密演算法、整理传送资料与接收回传资料,以及交易失败的处理,通常不同付款方式的传送与接收资料回不大相同,而且还会分即时回传以及非同步回传的状态,像是信用卡结完帐就能立刻取得交易结果,但是 ATM 转帐或是超商代码缴费就必须等到顾客真的去付钱後金流商才会回传资料,所以这部分我会根据不同的付款方式来进行工时预估。

测试与除错

主要包含写自动化测试与人工测试交易失败是否有出现正确的提示讯息,以及尝试着用一些手法像是将订单金额改为 0 元订单看能否成功交易,最重要的是测试正式环境的运作是否一切正常,这时前置作业中的确认完成验收标准就可以当作是测试清单,来确保交易如预期中的结果。

当理解金流串接文件以及确认客户需求後,下一篇文章我们开始来搭建 WordPress 的本机开发环境,并且运用一些自动化指令码让 WooCommerce 开发环境可以自动一键安装完成,省去手动处理的时间。

本文同步发表於:https://oberonlai.blog/tw/woocommerce-payment-document


<<:  Day01-CRUD API 实作(一)事前规划、Laravel Sanctum 安装与设定

>>:  轻松跨越Windows地雷而不会被炸得粉身碎骨

【左京淳的JAVA WEB学习笔记】第六章 档案上传

档案上传与一般表单提交的格式不同。 一般表单提交默认enctype = "applicat...

[PoEAA] Domain Logic Pattern - Transaction Script

本篇同步发布於个人Blog: [PoEAA] Domain Logic Pattern - Tran...

Day 27: 架构的声音、整洁的架构 (待改进中... )

「你的应用程序架构尖叫了什麽呢? 当查看最高层目录结构和 package 中的原始码档案时,他们是...

[进阶指南] 错误边界 ( Day22 )

component 里 JavaScript 的错误常常会破坏 React 的内部 state,并...

ASP.NET MVC 从入门到放弃(Day12) -Class funtion return void 函式写法

接着来讲讲Class一些基本概念.... 我顺序有点搞错...这个要放在物件导向前面讲的才对 1.X...