【ITニュース解説】Integrating Lipa na MPESA (KCB MPESA STK Push) with Node.js

この記事では、Node.jsを使ってケニアのモバイル決済サービス「Lipa na MPESA（KCB MPESA STK Push）」をアプリケーションに組み込む方法を解説している。ケニアではモバイル決済がデジタル経済の基盤となっており、この統合はEコマースや学費支払いなど、さまざまなデジタルサービスで支払いを自動化するために非常に重要だ。システムエンジニアを目指す初心者でも、APIの基本的な概念から実際の支払い処理、そしてその結果の受け取りまでを段階的に学ぶことができる。

まず、プロジェクトを開始するための準備がいくつか必要になる。Node.jsはJavaScriptをサーバーサイドで実行するための環境であり、アプリケーションの構築に不可欠だ。Visual Studio Codeのようなテキストエディタは、コードを効率的に書くために推奨されるツールだ。さらに、KCB銀行のBuni APIポータルから「Consumer Key」と「Consumer Secret」というAPI認証情報を取得する必要がある。これらは、KCBのシステムにアクセスするための「鍵」と「秘密のパスワード」のようなもので、あなたのアプリケーションが正規のものであることをKCBに証明するために使われる。最後に、ngrokまたはTunnelmoleというツールも必要だ。これについては後ほど詳しく説明するが、ローカルで動いているアプリケーションを一時的にインターネット上に公開するために使われる。

次に、Node.jsプロジェクトの基本的な設定を行う。ターミナルで新しいディレクトリを作成し、その中でnpm init -yコマンドを実行してNode.jsプロジェクトを初期化する。その後、いくつかの重要なライブラリをインストールする。axiosは、アプリケーションからインターネット上の別のサービス（今回の場合はKCBのAPI）にデータ（HTTPリクエスト）を送ったり、その応答を受け取ったりするためのライブラリだ。expressは、Webアプリケーションを簡単に構築するためのフレームワークで、ユーザーからのリクエストを受け取ったり、応答を返したりする「サーバー」の役割を担う。dotenvは、先ほど取得したKCBの認証情報のような機密性の高い情報や、アプリケーションの設定値を安全に管理するために使われる。これらの情報はコードの中に直接書き込むのではなく、.envという別ファイルに保存し、dotenvライブラリを使って読み込むことで、セキュリティを高め、設定の変更を容易にするのだ。

必要なライブラリをインストールしたら、.envファイルを作成し、KCBから取得したCONSUMER_KEYやCONSUMER_SECRET、KCBのAPIのベースURL、アプリケーションが動作するポート番号などの情報を設定する。また、STK Pushをテストするための電話番号、支払い金額、請求書番号、組織のショートコード、そして支払い結果を受け取るためのコールバックURLもこのファイルに記述する。これらの環境変数を適切に設定することで、コード自体を変更することなく、異なる環境やテストシナリオに対応できるようになる。

いよいよアプリケーションのメインロジックを記述する。index.jsというファイルを作成し、expressやaxios、dotenvといったライブラリを読み込むことから始める。express.json()とexpress.urlencoded()というミドルウェアを設定することで、Webリクエストのボディ部分にJSON形式やURLエンコード形式で送られてきたデータをアプリケーションで簡単に扱えるようになる。

このアプリケーションの最初の重要な機能は、KCBのAPIにアクセスするための「アクセストークン」を生成することだ。これは、KCBのAPIを使うたびに毎回認証情報を送る手間を省き、セキュリティを向上させるための仕組みである。generateTokenという非同期関数を作成し、その中でCONSUMER_KEYとCONSUMER_SECRETをコロンで連結し、それをBase64という形式でエンコードする。これは、HTTPリクエストのヘッダーに認証情報を安全に含めるための一種の暗号化だ。このエンコードされた認証情報を使い、axiosを使ってKCBの認証エンドポイントにPOSTリクエストを送信する。成功すれば、KCBからaccess_tokenという文字列が返され、これ以降のAPIリクエストでこのトークンを「Bearerトークン」としてヘッダーに含めることで、認証済みのリクエストとして扱われるようになる。

アクセストークンが取得できたら、いよいよSTK Push（支払い要求）を開始する機能に進む。/stkpushというエンドポイントにアクセスすると、アプリケーションはまずgenerateToken関数を呼び出してアクセストークンを取得する。その後、このトークンをAuthorizationヘッダーに含め、axiosを使ってKCBのSTK Push APIエンドポイントにPOSTリクエストを送信する。このリクエストのボディには、支払いを要求する電話番号、金額、請求書番号、そして重要な「コールバックURL」などの情報が含まれる。コールバックURLは、支払い処理が完了した後にKCBが結果を通知するために使用する、アプリケーションの公開されたWebアドレスだ。

そして、最も重要な部分の一つが「コールバックエンドポイント」の処理である。KCBが支払い処理を完了すると、先ほど指定したコールバックURLに対してPOSTリクエストを送信し、その中に支払い結果の詳細情報を含めてくる。アプリケーションでは/callbackというエンドポイントを設け、KCBからのこのリクエストを受け取る。受け取ったデータはreq.bodyを通じてアクセスでき、例えばfs.appendFileというNode.jsのファイルシステムモジュールを使って、そのデータをcallback.logというファイルに追記することで、支払い履歴を記録・確認できるようになる。これにより、支払い成功、失敗、キャンセルといった様々な結果をシステム側で把握し、次の処理（例えば、注文ステータスの更新など）へと繋げることが可能になる。

ここまででアプリケーションの主要な機能は完成するが、KCBがローカルで動いているアプリケーションの/callbackエンドポイントに直接アクセスすることはできない。KCBのシステムはインターネット上にあり、あなたのパソコンは通常、外部から直接アクセスできないプライベートなネットワーク内にあるからだ。そこで、tunnelmole（またはngrok）のようなツールが必要になる。tunnelmoleは、ローカルマシンで動いているアプリケーションの特定のポート（今回の場合はExpressアプリケーションがリッスンしているポート3000）を、一時的にインターネット上に公開してくれるサービスだ。npm install -g tunnelmoleでグローバルにインストールし、新しいターミナルでtunnelmole 3000と実行すると、https://tmole.io/abcd1234のような形式の公開URLが発行される。このURLを.envファイルのCALLBACK_URLに設定することで、KCBは支払い結果をあなたのローカルアプリケーションに直接送信できるようになる。これは、開発中に外部サービスとの連携をテストする上で非常に便利な仕組みだ。

すべての準備が整ったら、node index.jsコマンドでアプリケーションを起動する。サーバーが正常に起動すると、http://localhost:3000/stkpushというURLにブラウザでアクセスしてみる。すると、設定した電話番号のM-PESAアカウントに対してSTK Pushのポップアップ（M-PESAのPIN入力画面）が表示されるはずだ。これは、アプリケーションがKCBのSTK Push APIを正常に呼び出せたことを示している。ブラウザには、STK Pushが正常に受け付けられたことを示すKCBからの応答が表示される。

M-PESAのPINを入力して支払いを完了させると、KCBは先ほど設定したtunnelmole経由のコールバックURL（/callbackエンドポイント）に支払い結果を送信する。アプリケーションのターミナルには、KCBから送られてきた結果（例えば、"ResultCode": "0"は成功を示す）が表示され、同時にcallback.logファイルにもその詳細が記録される。これにより、支払いが成功したか、キャンセルされたか、あるいはその他の状態にあるかを正確に把握できるようになるのだ。

この一連の流れを構築することで、KCBのAPIトークンを生成し、STK Pushリクエストを送信し、そしてKCBからの支払い結果のコールバックをローカルマシンで受け取るNode.jsアプリケーションが完成する。この統合は、Eコマースサイトでの商品購入、学校の学費支払い、その他のデジタルサービスにおいて、顧客からの支払いをプログラムによって自動的に収集するための基盤となる。さらに、このシステムを拡張して、受け取った支払い情報をデータベースに保存したり、Webまたはモバイルアプリから支払い要求をトリガーしたり、既存のEコマースプラットフォームや学費管理システムと連携させたりすることも可能になる。