【ITニュース解説】How to Integrate KCB M-PESA STK Push API

KCB M-PESA STK Push APIは、企業や開発者が顧客から直接、携帯電話を通じて安全に支払いを受け取るための仕組みを提供する。このAPIを使うことで、ウェブサイトやアプリケーションから顧客の携帯電話に支払い依頼をプッシュ通知として送信し、顧客は自身の携帯電話上でPINを入力するだけで支払いを完了できる。これにより、支払いプロセスが簡素化され、ユーザー体験が向上し、ビジネス側もスムーズな支払いの回収が可能となる。システムエンジニアとしてこのAPIを連携させるには、大きく分けて「認証」「STKプッシュリクエストの送信」「コールバックの処理」という一連の流れを理解し、実装する必要がある。

まず、APIを利用するための最初のステップは「認証」である。これは、あなたが正当な利用者であることをシステムに証明する作業で、システムへのアクセス許可証（アクセストークン）を受け取るために行う。認証には、KCBから事前に提供される「Consumer Key」と「Consumer Secret」という二つの秘密の情報が必要になる。これらの情報は、ユーザー名とパスワードのようなものであり、他の人に知られないように厳重に管理する必要がある。具体的な手順としては、特定の認証用URLに対して、これらのConsumer KeyとConsumer Secretを組み合わせ、Base64という形式でエンコードしたものを「Authorization」というヘッダー情報に含めてPOSTリクエストを送信する。このリクエストが成功すると、APIは「access_token」という文字列を応答として返してくる。このaccess_tokenは、その後に行うすべてのAPIリクエストで「Bearerトークン」として使用する非常に重要な情報で、有効期限（通常は1時間）が設定されているため、期限切れの場合は再度取得し直す必要がある。

次に、この取得したaccess_tokenを使って、実際に顧客の携帯電話に支払いリクエストを送信する「STKプッシュリクエストの開始」に進む。これは、顧客に支払いを促すためのプッシュ通知を送信する行為である。認証時と同様に、特定のAPIエンドポイントに対してPOSTリクエストを送信する。この際、リクエストの「Authorization」ヘッダーには、先ほど取得したaccess_tokenを「Bearer」というタイプで含める。また、「Content-Type」ヘッダーにはapplication/jsonを指定し、リクエストの本体（ボディ）には支払いに関する詳細な情報をJSON形式で含める必要がある。必要な情報としては、支払いを要求する「顧客の電話番号」、支払い「金額」、任意で指定できる「請求書番号」、KCBが提供する共通のショートコードを使用するかどうかを示すsharedShortCode、自社の「PaybillまたはTill番号」（orgShortCode）、KCBから割り当てられる「組織のパスキー」（orgPassKey、通常は空欄）、支払い結果を受け取るための「コールバックURL」、そして取引の簡単な「説明」などがある。特にcallbackUrlは、HTTPSで始まるセキュアなURLを指定する必要があり、このURLが後の支払い結果通知の受け口となるため、非常に重要である。

STKプッシュリクエストが成功裏にKCBのシステムに受け付けられると、APIからは「Success. Request accepted for processing」（成功。処理のためにリクエストが受け付けられた）という内容の応答が返ってくる。この応答には、「MerchantRequestID」や「CheckoutRequestID」といった、今回の支払いリクエストを一意に識別するためのIDが含まれる。また、「ResponseCode」が「0」であれば、リクエストが正常に受け付けられ、顧客の携帯電話へのプッシュ通知が開始されたことを意味する。この段階ではまだ顧客による支払いは完了しておらず、システム側では「支払いリクエストを送信した」状態である。顧客の携帯電話には支払い金額と取引内容が表示され、PINの入力を促すメッセージが届くことになる。

顧客が自身の携帯電話でPINを入力し、支払いを完了させると、KCBのシステムは、STKプッシュリクエスト時に指定した「callbackUrl」に対して、支払い処理の最終結果を自動的に送信する。これが「コールバック応答」であり、この情報を受け取ることで、システムは支払いが実際に成功したのか、それとも失敗したのかを正確に把握し、その後の処理（例えば、商品の発送やサービスの提供など）を決定できる。コールバックのデータには、「ResultCode」という重要な値が含まれており、これが「0」であれば取引が成功したことを示す。その他の値は、ユーザーがPINを間違えた、取引をキャンセルした、電話に到達できなかった、といった失敗理由を細かく示す。成功時には、支払われた「金額」、「MpesaReceiptNumber」（M-PESAの取引ID）、取引が実行された「日時」、そして支払いを行った「顧客の電話番号」といった詳細な情報も含まれるため、これらの情報を使って自社のシステム内の取引記録を更新することが可能となる。

APIの利用中に発生しうるエラーについても理解しておく必要がある。例えば、認証トークンが無効な場合は「Invalid Credentials」エラーが、必要な認証情報が提供されていない場合は「Missing Credentials」エラーが返されることがある。また、STKプッシュリクエストの際に指定したパラメータに不足があったり、形式が正しくなかったりすると、「Bad Request - Invalid Remarks」のようなエラーが発生する場合がある。これらのエラーは通常、APIからの応答で「statusCode」や「ResponseCode」が「0」以外となることで示される。さらに、HTTPステータスコードもAPI通信の状態を示す重要な指標となる。例えば、200 OKはリクエストが正常に処理されたことを、400 Bad Requestはリクエストの内容に問題があることを、401 Unauthorizedは認証情報が無効であることを、500 Internal Server ErrorはAPIサーバー側で予期せぬエラーが発生したことをそれぞれ意味する。これらのコードを適切にハンドリングすることで、堅牢なシステムを構築できる。

実際にプログラミングする際には、Node.js、PHP、Pythonなどの言語で提供されているコード例が非常に参考になる。これらの例は、認証トークンの取得からSTKプッシュリクエストの送信、そしてエラーハンドリングまでの一連の処理を具体的に示しており、どのようにHTTPリクエストを構築し、JSONデータを送信・受信するかといった基本的な実装方法を学ぶのに役立つ。開発者はこれらのサンプルコードを参考にしながら、自身のアプリケーションに合わせた形でAPI連携部分を実装することになる。

開発が完了し、テスト環境での動作確認が済んだら、いよいよ実際の顧客が利用する本番環境への移行（Go-Live）手続きが必要となる。これには、KCBが指定する正式な申請書を提出し、承認を得る必要がある。何か疑問点や不明な点が生じた場合は、KCBの担当部署（buni@kcbgroup.com）に問い合わせることでサポートを受けることができる。このように、認証からリクエスト、コールバック処理、そしてエラーハンドリングまでの一連の流れを理解し、適切に実装することで、KCB M-PESA STK Push APIを利用した安全で効率的な支払いシステムを構築できる。