【ITニュース解説】Integrating Pesapal API 3.0 on Django

システムエンジニアを目指す初心者がWebアプリケーションに決済機能を組み込む際に役立つ、Pesapal APIとDjangoフレームワークを連携させる方法を解説する。Pesapalは、ケニアやウガンダなどアフリカ諸国で安全かつ便利なデジタル決済サービスを提供するフィンテック企業である。この解説は、DjangoプロジェクトでPesapal APIを使ってスムーズな取引を実現するための具体的な手順を段階的に説明する。

まず、Pesapalのサービスを利用するために、Pesapal開発者ポータルにアクセスし、ビジネスアカウントを作成する必要がある。アカウントが正常に作成されると、登録したメールアドレスに「Consumer Key」と「Consumer Secret」という二つの重要な情報が送られてくる。これらは、アプリケーションがPesapal APIにアクセスする際に自身を認証するための「鍵」のようなもので、外部サービスと連携する際には必ず必要となる。Djangoプロジェクトが既に準備できていることを前提として話を進める。

次に、プロジェクトで必要なライブラリをインストールする。まず、requestsライブラリをインストールする。これは、PythonアプリケーションからHTTPリクエストを送信し、Pesapal APIと通信するために使われる。次に、python-decoupleをインストールする。このライブラリは、APIキーやシークレットキーのような機密情報を、コードに直接書き込まずに.envというファイルで管理するために使用される。これにより、セキュリティが向上し、開発環境と本番環境で異なる設定を簡単に切り替えることができる。さらに、djangorestframeworkもインストールする。これは、DjangoプロジェクトでRESTful APIを構築するための強力なフレームワークであり、Pesapalとの連携部分でAPIエンドポイントを作成するのに役立つ。

インストールが完了したら、環境変数を設定する。プロジェクトのルートディレクトリに.envファイルを作成し、先ほど取得したConsumer KeyとConsumer Secret、そしてPesapal APIのベースURLを記述する。ベースURLには開発用の「サンドボックス」環境と本番用の「プロダクション」環境の二種類があり、最初はサンドボックスURLを使用する。また、後で取得するIPN IDもここに設定する場所を確保しておく。これらの設定値は機密情報のため、.envファイルに保存することでコードから分離し、バージョン管理システムにアップロードされるのを防ぐ。その後、Djangoのsettings.pyファイルにpython-decoupleからこれらの環境変数を読み込むコードを追加する。これにより、アプリケーションはコードに直接値を書かずに、外部ファイルから安全に設定値を読み込めるようになる。

次に、メインアプリケーション内にpesapal_service.pyというファイルを作成する。このファイルは、DjangoアプリケーションとPesapal APIとの間の連携の中核を担う。具体的には、以下の主要な機能がここに実装される。 一つ目は、Pesapalとの認証を行うためのアクセストークンを生成する機能である。Pesapal APIへのすべてのリクエストはOAuthアクセストークンを必要とする。この機能は、PesapalのRequestTokenエンドポイントを呼び出し、一定時間有効なトークンを取得する。 二つ目は、IPN（Instant Payment Notification）URLの登録と、登録済みのIPNリストを取得する機能である。IPNは、Pesapalが決済ステータスの変更などを非同期的にシステムに通知するための仕組みであり、IPN URLはその通知を受け取るエンドポイントを指す。 三つ目は、注文をPesapalに送信する機能である。この機能は、金額や説明などの取引詳細をPesapalに渡し、顧客が安全な決済ページで支払いを完了するためのリダイレクトURLを返す。 四つ目は、取引ステータスを確認する機能である。決済が成功したかどうかを確認することは、商品やサービスを提供する前に非常に重要である。この機能は、取引IDとマーチャント参照情報を使ってPesapalから決済ステータスを取得する。 これらの機能は、本番環境で使用する際には、トークンのキャッシュ（毎回新しいトークンを取得するのを避けるため）、エラーハンドリング（予期せぬエラーに対応するため）、そして関数の目的や引数、戻り値を明確にするためのドキュメント文字列の追加などを考慮に入れる必要がある。また、決済完了後には、決済情報をデータベースに保存するため、models.pyファイルにPaymentモデルのような形で、注文ID、金額、ステータス、追跡IDなどのフィールドを持つモデルを定義することが推奨される。

次に、決済処理に関連するDjangoのビューを作成する。これらのビューは、プロジェクトとpesapal_service.pyで定義した機能とを結びつける役割を果たす。 get_token_viewは、テストやデバッグ目的でPesapalのOAuthトークンを生成し、返すためのビューである。 register_ipn_viewは、IPN URLをPesapalに登録するためのビューで、list_ipns_viewは登録済みのIPN URLのリストを取得するためのビューである。 create_order_viewは、新しいPesapal注文を作成するための主要なビューである。このビューは、リクエストボディまたはフォームデータから決済金額などの情報を受け取り、pesapal_service.pyのsubmit_order_request関数を呼び出す。その結果として、顧客をPesapalの決済ページにリダイレクトするためのURLを返す。ペイロードには、一意の注文ID、通貨、金額、説明、コールバックURL、通知ID、顧客の請求先情報などが含まれる。 ipn_listenerは、Pesapalからの非同期的なIPN通知を受け取るためのエンドポイントである。Pesapalは決済ステータスの変更時にこのURLに情報を送信し、アプリケーションはそれに基づいてデータベースを更新できる。 payment_confirmは、顧客がPesapalでの決済を完了した後にリダイレクトされるコールバックエンドポイントである。ここで、Pesapalから渡された追跡IDとマーチャント参照情報を使用して、get_transaction_status関数で最終的な決済ステータスを確認する。決済が「COMPLETED」（完了）していれば、成功ページ（例：ダッシュボード）にリダイレクトし、それ以外の場合は支払い失敗ページを表示する。 開発中は、ローカル環境のWebサーバーをインターネットに公開するためにngrokのようなツールが非常に役立つ。外部サービスであるPesapalは、localhostのようなローカルアドレスには直接通信できないため、ngrokを使ってローカルサーバーに公開URLを割り当て、callback_urlやALLOWED_HOSTSにそのURLを設定することで、Pesapalからの通知を受け取ることが可能になる。

作成したビューに対応するURLパスを、Djangoプロジェクトのメインアプリケーションのurls.pyファイルに設定する。これにより、特定のURLにアクセスがあった際に、適切なビュー関数が実行されるようになる。例えば、"/pesapal/token/"というパスをget_token_viewに紐付けたり、"/pesapal/order/create/"をcreate_order_viewに紐付けたりする。

最後に、PesapalにIPN URLを登録する。登録済みのIPNリストを取得するビュー（例: https://yourdomain.com/pesapal/ipn/list/）を実行し、その結果からIPN IDを取得する。このIDをsettings.pyで設定したPESAPAL_IPN_ID環境変数に記述する。

これらのステップが完了したら、決済フロー全体をテストする。リダイレクトが正しく機能するか、コールバックによって決済ステータスが更新されるか、IPNがエンドポイントに到達するかを確認する。本番環境へ移行する際には、.envファイル内のPesapal APIのベースURLを本番用URLに切り替え、Consumer KeyとConsumer Secretも本番用のものに更新する必要がある。また、セキュリティのためにHTTPSの使用、適切なエラーロギングを含むエラーハンドリングの実装、コールバックURLに適切なドメインを設定することなども考慮に入れる必要がある。

上記がPesapal APIをDjangoプロジェクトに統合するための基本的な手順である。Pesapalは他にも定期決済、返金リクエスト、注文キャンセルといった多くのサービスを提供しているが、これらは公式ドキュメントで詳細を確認できる。