daraja-restful:用 Pascal 优雅对接 M-Pesa Daraja API
一、这是什么
daraja-restful 是一个使用 Free Pascal / Delphi 编写的小型 RESTful 客户端库,用于对接 Safaricom M-Pesa Daraja API。Daraja 是肯尼亚电信运营商 Safaricom 提供的移动支付开放平台,开发者可以通过它实现手机钱包收款、支付、查询交易状态、退款、账单校验等能力。
在 PHP、Node.js、Python、Java 社区里,针对 Daraja 的 SDK 一抓一大把;但在 Pascal 世界,这类现成的封装几乎没有。daraja-restful 就是为了填补这个空白而诞生的——它让长期使用 Object Pascal 做后端(尤其是一些非洲本地企业仍在大量使用 Delphi/FPC 构建系统)的开发者,不必再为了接一次 M-Pesa 就临时装上另一种语言运行时。
项目规模很小,代码风格朴素直接,定位是”够用的封装“而不是”全功能框架”。适合拿来即用,也适合作为一个学习 Pascal 调用现代 REST API 的参考样本。
二、它解决了什么问题
直接调用 Daraja API 并不是”发个 HTTP 请求”那么简单,真实接入时有几个门槛:
- OAuth 认证:Daraja 使用 OAuth 2.0,需要先用
Consumer Key + Consumer Secret换取 Bearer Token,且 Token 有有效期(通常 1 小时),过期要重新获取。 - Basic Auth 构造:换取 Token 的请求本身需要把 Consumer Key/Secret 拼接后做 Base64 编码并放入
Authorization: Basic ...头。 - 请求体格式:几乎所有业务接口(STK Push、C2B、B2C、查询等)都要求 JSON body,且字段命名、大小写、必填项都很挑剔。
- 响应解析:返回的是 JSON,需要按字段取值并做错误判断(
ResponseCode、errorCode、errorMessage等)。 - 加签:部分接口(如 C2B 的 URL 注册、部分安全接口)需要 RSA 或特定签名。
这些重复劳动如果每接一个项目都手写一遍,很快就会出现样板代码泛滥。daraja-restful 把这些套路收敛到一组 Pascal 单元里,让你用几行代码完成一次支付发起或状态查询。
三、它大概长什么样
说明:以下为对项目典型用法的说明性示例,具体类名/方法签名请以实现为准。阅读源码时以
daraja-restful仓库中的单元(.pas)文件为准。
一个典型的调用流程大致是:
uses
daraja_client, daraja_types, fpjson;
var
Client: TDarajaClient;
Resp : TJSONObject;
begin
Client := TDarajaClient.Create;
try
// 1. 配置环境凭证
Client.Environment := deSandbox; // 沙箱 / 生产
Client.ConsumerKey := 'your-consumer-key';
Client.ConsumerSecret:= 'your-consumer-secret';
Client.ShortCode := '174379';
Client.PassKey := 'your-lipa-na-mpesa-passkey';
Client.CallbackURL := 'https://example.com/mpesa/callback';
// 2. 获取 OAuth Token(内部会缓存)
Client.Auth;
// 3. 发起 STK Push(Lipa na M-Pesa Online)
Resp := Client.StkPush(
'254712345678', // 手机号(国际格式,不带 +)
100, // 金额,以 KES 为单位
'INV-0001', // AccountReference
'Payment for order 0001' // TransactionDesc
);
try
WriteLn('CheckoutRequestID = ', Resp.Get('CheckoutRequestID', ''));
finally
Resp.Free;
end;
finally
Client.Free;
end;
end;
关键点:
Auth方法封装了 OAuth 换取 Token 的全过程,包括 Basic Auth 头的构造和返回 JSON 里access_token的提取,通常还会把这个 token 缓存在客户端实例上,避免每次都去换。- 业务方法返回
TJSONObject,把解析的主动权交给调用方,这一点很符合 Pascal 生态里fpjson/SuperObject的惯用法——库不替你定义一大堆 DTO 类型,你按需取字段。 Environment切换沙箱/生产,Daraja 的沙箱和生产 base URL 是固定的两条,把它做成枚举避免手写 URL 出错。- Callback URL 由业务侧提供,库本身是”发起端”,异步回调的处理要由你自己的 Web 服务(比如
fpweb、mORMot、Delphi Datasnap等)去接收。
四、技术栈与依赖
从项目性质来看,它依赖的是 Pascal 生态里最常见的两件工具:
- HTTP 客户端:
fphttpclient(Free Pascal)或RESTRequest/TIdHTTP(Delphi 侧),负责发 HTTPS 请求、设置 header、读响应体。 - JSON 处理:
fpjson+jsonparser(FPC 自带)或项目自己选定的 JSON 库。
这意味着它不需要第三方商业组件,用 LTS 版 FPC 或较新版本 Delphi 拉下来就能编译,可移植性不错。如果你的项目已经在用 Lazarus 或做了跨 FPC/Delphi 兼容,这个库几乎零接入成本。
五、设计取向与权衡
这个小项目有几个比较”务实”的设计取向,值得点出来:
1. 不做过度抽象。 没有为了”接口即一切”而设计大量抽象类,也没有自己搞一套 HTTP 层。业务逻辑直接落在 JSON 之上,读起来一目了然。代价是类型安全性弱一些——字段名写错要运行时才暴露。
2. 把 OAuth 生命周期管起来。 Token 过期是 Daraja 接入最常见的踩坑点,把”取 token”和”用 token”合并在客户端对象里,比每次请求前都手动换 token 要省心得多。
3. 回调是”责任边界”。
Daraja 的 STK Push 是异步的:你调用一次,用户手机上弹出支付框,支付结果通过 CallbackURL 以 POST 的形式推回来。这个回调需要你自己的 Web 服务去响应、验签、入库。daraja-restful 只负责”发出去”,”接回来”留给你——这是合理的职责划分,因为回调的处理策略高度依赖业务系统。
4. 沙箱友好。 有沙箱环境是 Daraja 的一大优势,库显式区分环境,能让开发者在正式接入前把整条链路跑通。
六、典型使用场景
- Pascal 后端项目接 M-Pesa:用 Delphi/FPC 写的 ERP、POS、订单系统想直接支持手机支付,
daraja-restful让你不必再引入一个 Node/PHP 中间层。 - 桌面/嵌入式 POS 写 M-Pesa 支付:在收银终端上直接发起 STK Push,弹出付款框,异步回调在收银服端接收。
- 作为学习样本:想学 Pascal 怎么优雅地调用现代 REST API(OAuth、Basic Auth、JSON 请求/响应、错误处理),这个库代码量不大,通读一遍能覆盖大部分模式。
七、需要注意的地方
- 本项目体量较小、属于个人开源项目,生产接入前建议通读源码,确认对错误处理、超时、重试、并发 token 刷新的处理是否满足你的场景。
- 敏感凭证不要写死在代码里,
Consumer Secret、PassKey一旦泄露等同于账户被接管;应当从环境变量或加密配置中读取。 - HTTPS 与回调验签:生产环境必须使用 HTTPS 回调,并在回调处理端校验来源与字段,防止伪造支付通知。
- Daraja 的字段与文案会变:Safaricom 对 Daraja 做过多次版本迭代(例如发票单价、描述字段的必填性、响应码枚举等),接入时以官方文档当前版本为准,别完全依赖第三方库的默认值。
八、总结
daraja-restful 的价值不在于”功能多”,而在于它填上了 Pascal 生态和 M-Pesa 支付之间那块缺失的拼图。它遵循 Pascal 社区偏爱的简洁直白风格,把 OAuth、HTTP、JSON 这些重复性的胶水代码封装成一组小而清晰的单元,让 Free Pascal / Delphi 项目能以最少的额外依赖接入肯尼亚最主流的移动支付渠道。
如果你正用 Object Pascal 做后端,又恰好需要支持 M-Pesa,那么值得先把它拉下来读一读——无论最终直接用它,还是照它的思路自己封装一层,这份”在 Pascal 里调 REST API”的经验都能复用。



还没有评论,来说两句吧...