JJUG CCC Fall 2023 登壇レポート / 開発者向けブログ・イベント

11月11日に野村コンファレンスプラザ新宿で開催されたJavaコミュニティイベント「JJUG CCC 2023 Fall」のスポンサーセッションに、GMOペイメントゲートウェイ株式会社システム本部橋本莉奈が登壇しました。セッションでは従来のレガシーシステムから脱却すべく、OpenAPIをベースとした新システムを構築する過程で遭遇した課題やその解決策、成果について紹介しました。

登壇者

GMOペイメントゲートウェイ株式会社
システム本部決済サービス統括部マルチペイメントサービス部決済開発第2グループ
橋本莉奈

オンライン総合決済サービス「PGマルチペイメントサービス」が抱えていた課題

GMOペイメントゲートウェイ（以下、GMO-PG）が2008年より提供するオンライン総合決済サービス「PGマルチペイメントサービス」は、多様な決済手段を一括導入できるプラットフォームです。EC事業者と各決済事業会社との「契約」「決済情報」「お金のやり取り」をつなぐ役割を担っており、加盟店様は同サービスを利用することで、決済手段の一括導入・契約の一本化が可能になります。

サービス開始当時、決済手段は4つのみでしたが、国内オンライン市場の決済手段の多様化により、現在の決済手段は30を超えています。これに伴い、決済APIも複雑になってきています。

PGマルチペイメントサービスの接続方式は、リンク型とWebAPI型の大きく2つに分けられます。リンク型は、加盟店様のECサイト上で決済ボタンを押すとGMO-PGの決済画面に遷移するという方式です。一方で、WebAPI型は、裏側の決済処理のみGMO-PGで行い、決済画面は加盟店様で用意してもらう方式です。

WebAPI型にはもともと、GMO-PG独自の接続仕様であるプロトコルタイプと、GMO-PGで作成した決済処理プログラムを加盟店様のサーバに導入するモジュールタイプの2種類がありましたが、今回、新たにOpenAPIタイプを追加することになりました。

OpenAPIタイプを追加するに至った背景には、2つの課題がありました。橋本は次のように説明します。

「1つめの課題は、既存の接続方式が弊社独自のレガシーな接続仕様となっていたこと。利用者への影響が大きいと考えられるためシステム変更が難しい一方で、現代のWeb標準と比較すると学習コストの高いプロダクトとなっていた。

2つめは、決済手段ごとにコンセプト、フロー、データ、用語のばらつきがあること。サービス提供開始当時はここまで決済手段が増えることを想定しておらず、決済手段が増えるたびに機能を継ぎ足していった結果、フローやデータなどが決済手段ごとにばらばらになった。結果として、APIが複雑化し、それぞれ個別実装しようとするとかなりの開発コストがかかる状況になっていた」（橋本）

OpenAPIタイプの新しい接続方式の特徴

こうした既存の接続方式の課題を解消すべく、2023年8月に正式リリースされたのが「OpenAPIタイプ」という新しいWebAPIの接続方式です。その特徴は大きく分けて4つあります。

1つめは、決済手段の追加が簡単である点です。各決済手段を、クレカ払い、Pay払い、現金払いの3つのグループに分類してAPIを集約することにより、加盟店様は1つのグループに対し1度開発を行うことで、同じグループの決済手段を容易に追加できるようになります。

2つ目は、グローバルスタンダードなWebAPIに準拠している点です。今回は世界標準であるOpenAPI Specification（OAS）をベースとした接続仕様となっており、その他のWeb標準技術も積極的に採用しています。

3つ目は、安心安全な決済という点です。PCI DSSの準拠、不正利用対策、冪等性のサポート、暗号化スイートの強化のほか、現在OAUTH2.0認証を準備しています。

そして、4つ目が既存の接続方式との互換性です。既存方式を利用している利用者は、既存の取引情報や登録済みの会員データをそのまま利⽤できます。既存の接続方式を利用しながら、一部の処理を新規接続方式に移行するといった併用も可能です。

採用した技術スタック

今回採用した技術スタックは下記のとおりです。

OASを導入するメリットは多くあります。まず、世界標準のフォーマットであるため、設計者による記述のばらつきが発生しづらい点です。また、この仕様に則ることで、コーディングの一部を自動化でき、便利な公開ツールによってテストも効率化できます。定義がテキストベースであり、バージョン管理ツールとも相性がよいといえます。

さらに、つなぎこみの開発をするなかでよく発生する問題も解決できます。橋本は「たとえば、これまでの接続方式では膨大なAPI仕様書のなかから手に入れたいファイルを探して見つけなければならなかったが、OASを利用することで、最新のAPI仕様書をWebでいつでも確認できるようになる」と説明します。

また、開発の段階においては従来、手動実装によるパラメータ名の記述間違いなどの発生リスクがありましたが、OASを利用しパラメータのコードをツールで自動生成することによりヒューマンエラーが発生しづらくなります。

プロジェクトはスキーマ駆動開発で進行

今回のプロジェクトは、ecbeing社と協力してスキーマ駆動開発で進められました。ecbeing社はECサイト構築で国内最大シェアを誇るトップベンダーです。橋本は「ecbeing社とはAPIリファレンスとOASファイルでやり取りし、実際にGMO-PGのAPIを利用してもらい、フィードバックをもらい、アップデートを加えるというサイクルを繰り返した」と振り返ります。

このような手法を採用することにより、GMO-PGとしてはコードが自動生成できるようになり、仕様変更への心理的障壁が下がり、アップデートを気軽に行えるようになるというメリットがあります。一方でecbeing社としては、コード自動生成によって、仕様変更が生じてもすぐに対応できるというメリットがあります。今回のプロジェクトにおいても、リリース直前にもかかわらず大きなアップデートをかけることができたといいます。

クライアントサイドもサーバサイドも、ツールを利用すれば下記のようなコマンドを実行することでコードを自動生成できます。

APIリファレンスにもさまざまな工夫

今回は、Redoclyを利用してAPIリファレンスも自動生成しています。SwaggerUIやRedoclyなどのツールを利用すると、OpenAPIのYAMLファイルからHTMLを自動生成できます。橋本は「デフォルトのスタイルが整っているため、スタイルを適用しなくても、そのままで公開できるようなクオリティになっている」とツールを利用するメリットを話します。

しかし今回は、オリジナリティを出すため、GMO-PGのデザインチームによるデザインを適用しています。Redoclyは設定ファイルに基づいて自動生成したcssがhtmlに埋め込まれており、設定ファイルはjson形式で記述する必要があるため、今回はjsonファイルを作成しています。ただ、jsonのスキーマとHTMLの要素がどのように紐づいているのかドキュメントに記載がなく、その解析から行いました。

APIリファレンスを作成するにあたっては、API接続のための開発ガイドに関する説明を豊富に盛り込むように意識したともいいます。

「これまで加盟店様から受けてきた問い合わせの傾向を調査し、問い合わせが多かった内容を精査して、GMO-PGの開発エンジニアの経験も踏まえながら、開発者に迷いがないよう設計。海外PSP10社以上のリファレンスを調査・比較し、ドキュメント構成やパラメータ名なども参考にした。また、UXライティングも取り入れ、読み手に余分な負荷をかけず、何が言いたいのか伝わる文章を目指した」（橋本）

既存利用者の使いやすさを確保しながら安心安全な決済を実現する

今回、APIエンドポイントは、Remote Procedure Call（RPC）、いわゆる「手続き型」「アクション型」に基づいた設計にしています。当初はRESTfulなAPIにリニューアルすることで検討を進めていましたが、既存のAPI群が手続き型であるために、RESTfulに変えることで既存の利用者がシームレスに移行することが難しくなる状況を避けた形です。すべてのサーバー間リクエストのHTTPメソッドはPOST、リダイレクト処理はブラウザによってはcookieが抜け落ちる問題があるので、GETで統一しています。

API通信の認証はBasic認証方式を採用しています。これは、ID・パスワードを認証データとして利用している既存のWebAPIからの移行を簡単にするためです。ただし、よりセキュリティ的に強固なOAUTH2.0認証にも2024年より対応していく予定です。

最近の決済手段は、クレジットカードの3Dセキュア認証やPay払いなど、リダイレクトを含む処理が多いため、リダイレクトの方法についても気を使っています。今回、リダイレクト処理とコールバック処理はすべてGETで実現しています。また、安全に遷移ができるよう、csrfトークンをパラメータに含めて、なりすましや改ざん防止につなげています。

意図しない二重処理が発生する可能性を避けるため、冪等性がサポートされていることも重要です。冪等性とは、同じ操作を何度繰り返しても、同じ結果が得られる性質のことです。たとえば、ある取引を100円返金する際に、ネットワークエラー等で意図せず二重送信してしまうと、100円だけ返金したいのに200円返金されることがあります。OpenAPIタイプでは冪等性をサポートしており、二重決済は発生せずに、加盟店様は安全にリトライできます。

APIリクエストに対する処理結果を表すHTTPステータスコードは、OpenAPIタイプでは基本的にREST仕様に則って返却するようになっています。一般的に200系のコードはリクエスト成功を表しますが、今回のOpenAPIタイプでは200系を細かく分割しました。これは、リダイレクトの多い決済処理において、リダイレクトが必要なものを特定のステータスコードで返すようにすることで、加盟店様はコードを最初に見てリダイレクトすべきかどうか判断できるようになるためです。

APIリクエストがエラーになった場合、400系、500系のHTTPステータスコードを返却します。エラー情報はRFCのWeb標準仕様に従って、JSON形式で返却します。HTTPレスポンスヘッダーのContent-Typeは、application/problem+jsonで送信します。

OpenAPIタイプのAPIリファレンス（OASファイル）とAPI仕様はそれぞれバージョンがあります。APIリファレンスのバージョンは、メジャー・マイナー・パッチという3段階の変更基準があります。一方、API仕様のバージョンは、後方互換がない破壊的変更を伴うリリースが発生する際に、新規バージョンとなります。HTTPヘッダーのAPIバージョンを設定することでバージョン変更前の仕様が保証されるようになっているため、仕様変更に対応できていなくても加盟店様はAPIバージョンを指定することで、決済への影響を回避できます。

実は、既存のWebAPIには、リファレンスに載せていない「隠しパラメーター」があります。特定のお客様だけが利用できる裏メニューのようなもので、通常のリファレンスとは別のドキュメントを作って管理しています。しかし、OpenAPIタイプではOASにすべてを記述することもあり、隠すことが難しくなりました。解決策として、すべてのエンドポイントにadditionalOptionsという任意のMap形式のパラメーターを用意し、このMapに隠しパラメーターを設定してもらうようにしています。

おわりに

OpenAPIタイプの接続方式のリリースによって、これまで取引実績のなかったお客様からもお声がけいただけるようになったほか、決済手段の追加にハードルを感じていた既存のお客様からも高い評価を得ています。橋本は「OpenAPIタイプが今後より多くのお客様に愛されるプロダクトとなるよう、今後もプロダクトの価値向上に励んでいきたい」と意気込み、講演を締めくくりました。