まだプログラマーですが何か?

プログラマーネタ中心。たまに作成したウェブサービス関連の話も https://twitter.com/dotnsf

2020/11

「REST API の標準化」を考える機会がありました。実際に格納したり取得したりするデータ自体の構造は当然ケース・バイ・ケースになるわけですが、その呼び出し方とか、パラメータの指定方法とか、結果のフォーマットとかを社内や団体内で共通化すると、単に便利なだけでなく、一度使った後に新しい別の API を利用する際にも理解を早めることができます。

で、具体的にはどのように共通化すべきで、そこにはどういった要素が考慮されるべきか、といった内容を自分なりに考えてみました。

ここには色んな流派というか、考え方の基本となるパターンがあるのですが、今回は自分の経験を元に、自分はこういう API にしている、こういう API だとわかりやすい/覚えやすい、という基準で、自分なりに標準化したものを紹介します。


【考慮すべき要素】
詳しくは後述しますが、以下の6つについては標準化時に抑えておく必要がある要素であると思っています:

0. id と日付時刻の扱い
1. API をリクエストする際のメソッドと URI
2. API をリクエストする際のパラメータ
3. API からのレスポンス
4. セキュリティ
5. テスト
6. 公開方法



また、以下で説明する内容については、下図のような商品マスターデータ(items)を対象とした REST API を作ることを想定した例として紹介します:
idcategory_idnamemaker_idpriceimage_urlcreatedupdated
x100x051○○シャンプーx10001700http://xxxxx/100.jpg16054028361605402836
x101x051××シャンプーx10002800http://xxxxx/101.png16054038361605403836
x102x052□□コンディショナーx100101000http://xxxxx/102.jpg16054048361605404836
x103x053▲▲ヘアオイルx10001500http://xxxxx/103.jpg16054058361605405836
x104x061◎◎ボディソープx100211000http://xxxxx/104.png16054068361605406836
x105x071◆◆天然化粧水x100102000http://xxxxx/105.png16054078361605408836

※数字は全て integer 。category_id や maker_id は別途 category や maker のマスターデータが存在していて、外部参照キーだけが格納されているイメージです。


【0. id と日付時刻の扱い】
まずは API の考慮点というよりも、その API で対象とするデータにおける考慮点です。既に存在しているデータベース等を対象とする場合は今からの変更は難しいかもしれませんが、新たにデータベースから作成できるのであれば API 利用を想定した設計にしておくべき、という考慮点です。

まずいわゆる id 値について。基本的にはテーブル内でユニークな値であればよいのですが、ここを integer 型とすべきか string 型とすべきか、という考慮点があります。メリット・デメリットを考慮した上で選ぶべきであると思っています:
 メリットデメリット
integer 型・データ量が少ない
・データベース側に自動生成機能があることが多い
・推測しやすい、推測される可能性がある
string 型・存在する id の推測が困難
・値そのものに意味をもたせることも可能(例:メールアドレス)
・1件あたりのデータ量が増える(といっても現代では大したことはないかも)
・生成の仕組みが必要


どちらのケースも存在しているし、どちらか一方に不利な要素があるわけではないのですが、個人的には「今から新規に作るなら string 型」だと思っています。理由は「今では string 型のデメリットが大したことない」のと「 ID が自動生成されるミドルウェアでは string 型になることが多い」ので、結果的に「ID は string 型にした方が統一しやすい」と思っています。

ID に加えて、データレコードの作成日時(created)と最終更新日時(updated)は全てのレコードに加えるべきだと思っています。ソフトデリートを有効にする場合は削除日時(deleted、初期値は 0 か null)も加えます。


なお日付時刻については後述する特別な理由がない限りは UNIX タイムスタンプ値を使うべきです。YYYY-MM-DD のような特定の文字列フォーマットで格納してしまうとタイムゾーンを考慮することができなくなってしまうため、データとしてはタイムスタンプ値で格納し、表示する際に変換する、という方法が理想的です。

※ただし「日本からしか使わない」ことに加えて「特定日だけのデータを取り出す」といった用途がある場合などはあらかじめ日付フォーマット変換しておいた方が便利になることもあります。日付フォーマットを利用する場合は、そのフォーマットもあらかじめ標準化しておくべきです(YYYY-MM-DD とか YYYY-MM-DD hh:mm:ss など)。なお、このあたりは個別事情を考慮して対応する必要があるため、標準化ルールの対象外とする場合もあります。


【1. API をリクエストする際のメソッドと URI】
リクエスト時の考慮ポイントが1番多くあると思っています。順に説明します。

「メソッド」はいわゆる HTTP メソッドのことで、一般的には GET(取得・検索)、POST(作成)、PUT(更新)、DELETE(削除)が用いられます。API の用途や目的に合わせてメソッドを選びます。

より多くの考慮が必要なのは URI 部分となります。まず前提として以下の条件を逸脱しないよう注意してください:
  • 文字コードは UTF-8
  • リクエストデータに外字は使わない
  • URI ではキャメルケース(userData)ではなくスネークケース(user_data)を使う※
  • %(パーセント)でエンコーディングする必要があるデータは URI に含めない
※ホスト名部分が大文字・小文字の区別をしないためです

次にホスト名ですが、理想的にはホスト名の一部に "api" という文字が含まれていることが挙げられます。これが難しい場合はパス名のどこかに "api" を含めて、この URI が API のための URI であることを明示します。以下では api.mycompany.com というホスト名を使う想定で説明を続けます。

パス名の中には今後の仕様変更に対応できるよう、 API のバージョン("v1" など)を含めるようにします。

データの種類(この場合は items)も URI の一部に含まれている必要があります。このあたりから流派によって扱いに違いが出てくる部分ですが、自分は「単数を扱う API なら単数形(item)」、「複数を扱う API なら複数形(items)」としています。そして単数を対象とする場合はその id をパス内で指定するようにします。

例えば以下のようにする、ということです:
  • GET https://api.mycompany.com/v1/items (複数の items を取り出す
  • GET https://api.mycompany.com/v1/item/x100 (id = "x100" の item を取り出す
  • POST https://api.mycompany.com/v1/item (item を1件新規登録する)
  • PUT https://api.mycompany.com/v1/item/x101 (id = "x101" の item を更新する)
  • DELETE https://api.mycompany.com/v1/item/x102 (id = "x102" の item を削除する)
  • POST https://api.mycompany.com/v1/items (items をまとめてバルクインサートする)
  • DELETE https://api.mycompany.com/v1/items (items をまとめてバルクデリートする)
  •   :
リクエストした結果をどのようなフォーマットで取得するか、というフォーマットの指定も(特定フォーマットで固定、ということでなければ)リクエストに含めることができるべきです。一般的には URI の最後に拡張子の形で指定できるようにすることが多いようです:
  • GET https://api.mycompany.com/v1/items.json (複数の items を JSON で取り出す)
  • GET https://api.mycompany.com/v1/items.xml (複数の items を XML で取り出す)
  • GET https://api.mycompany.com/v1/item/x100.json (id = "x100" の item を JSON で取り出す)
  • GET https://api.mycompany.com/v1/item/x100.csv (id = "x100" の item を CSV で取り出す)
  •   :
拡張子が指定されていなかった場合は、エラー扱いとするか、またはあらかじめ決められたデフォルトフォーマットのリクエストに転送されて処理されるようにするか、を決めておきます。

なお、そもそも CSV で取り出すことができないようなデータ構造のオブジェクトを対象とする場合は無理に CSV に対応する必要はないと思っています。

また「検索」や「アップロード」といった処理については別の URI を用意することになります。



【2. API をリクエストする際のパラメータ】
一部 3. で考慮する内容も含まれるのですが、リクエスト時の URL パラメータをどのように標準化するべきかを記載します。

複数のデータが返ってくる可能性のある API を実行する場合、全データ量が膨大にならないようパラメータで制御することがあります。この例を使って以下を紹介します。

一般的には limit パラメータと offset パラメータを用いて取得範囲を指定します。limit は取得件数、offset は「何件目から」を指定するパラメータです。一般的に offset のデフォルト値は 0(1件目から)で、limit のデフォルト値は 100 以下が推奨されています:
  • GET https://api.mycompany.com/v1/items.json?limit=20&offset=100 (items を 100 件目から 20 件、JSON で取り出す)
  •   :

これら以外によく使われるパラメータとしては以下があります。どのようなパラメータに対応すべきかを事前に決めておきます:
パラメータ用途
sortソートキーを指定
since指定タイムスタンプ以降のデータを取り出す
until指定タイムスタンプ以前のデータを取り出す
fields実行結果に含まれるフィールド値を指定したものだけにする(カンマ区切り)


【3. API からのレスポンス】
API の(実行できなかったケースも含めた)実行結果にもある程度の共通化・標準化がされていると、実行後の処理ハンドリングに手間取ることが少なくなります。このレスポンスは (1) 成功した時と、(2) 失敗した時 の両方を考慮した上で標準化する必要があります。ただし KML や iCal, GeoJSON など、フォーマットが規定済みである場合は、そのフォーマットに従うものとします。

考慮点を以下に挙げますが、多くの場合で開発者はまず API を実行し、その結果を見て開発していく、という流れになります。そのため返却された内容で実行結果を判断できるようになっていることが望ましいと考えられます。

まず (1) 成功時のレスポンスデータには以下のような内容が含まれているべきと考えられます:
パラメータ用途
statusHTTP ステータス
resultset全データ件数、offset 値、limit 値
result実行結果(配列)


{
  status: 200,
  resultset: {
    count: 3,
    offset: 10,
    limit: 20
  },
  result: []
}


また (2) エラー時のレスポンスデータには以下の情報を返して原因追求できるようにするべきです:
パラメータ用途
statusHTTP ステータス
typeエラー種別
errorエラー内容


{
  status: 401,
  type: "not authorized",
  error: {
    message: "Not authorized to perform this operation."
  }
}

【4. セキュリティ】
フォーマットの取り決め、という意味での標準化は上述のような感じですが、フォーマット以外にも標準化の対象はあります。その1つがセキュリティ項目です。代表的なものを挙げてみました:
観点対策説明
通信の改ざん、盗聴通信暗号化SSL(https)通信に対応することで送受信データの信頼性担保および情報漏えいの防止を行う。
情報漏えいAPI キーなどによる認証API 利用者に認証をかけることで API を利用できる人を制限する。また利用者毎の利用頻度を確認できるようにすることで API キーが漏洩している可能性を早めに特定できるようになる。アクセストークンを利用する場合はアクセストークンの有効期間を適切に設定して、トークン漏洩時の2次被害を最小にする。
負荷対策利用制限、キャッシュAPI に DDoS 攻撃が行われることを想定した管理が必要。コール数に対する利用制限をかけたり、同一の GET リクエストに対してキャッシュレスポンスで対応する、など
クロスドメイン間の通信CORS 対応ウェブブラウザではクロスサイトスクリプティング防止の観点からクロスドメイン間通信は行わない仕様となっている。場合によってはクロスドメイン間通信を許可する必要が生じ、そのための対応が必要となる




【5. テスト】
API を実際に動かしてテストする上での、テスト環境やテスト方法を標準化することで、テスター担当者の負担を軽減することができます。

一般的には動作を確認できるようなフォームやサンプルプログラムを用意して実際に実行し、そのレスポンスを確認することになります。

なお、6. で後述する Swagger ドキュメントを利用することでテスト用フォームを自動生成することができます。


【6. 公開方法】
API をドキュメント化してテスターや開発者に公開するまでの流れを標準化する、という項目です。このための各種ツールも存在していますが、以下では Swagger ドキュメントを紹介します。

Swagger ドキュメントは Open API Initiative が提供するオープン企画 "OAS" で採用されている REST API のドキュメント化規格です。

Swagger Editor や、YAML による特定フォーマットで API を記述することで、インタラクティブなドキュメント UI を生成することができます。単に URI やパラメータの説明をするだけでなく、実際にAPI を動かすことができる、という点が最大の特徴となっています。開発者視点では実際に API の動作を確認しながら仕様を確認できるのでとても有用な API ドキュメントといえます:
2020111801



【参考】
 内閣官房情報通信技術(IT)総合戦略室  API テクニカルガイドブック

そろそろ、その時はやって来たかな?
時は来た!


これまでメインのプログラミング開発環境を Windows10 の WSL(Windows Subsystem for Linux)Ubuntu 18.04 にしていました。WSL2 のことはもちろん知っていましたが、メイン機のスペックが特別高いわけでもなく(メモリ 8GB)、WSL で困らないであろう範囲のプログラミングをメインにしていました(例えばコンテナ環境が必要になった場合は別環境に用意して、そこにアクセスする、など)。

一方で WSL2 をサポートする開発周辺環境も整ってきました。Docker Desktop for Windows もリリースされ、もう mac と比較しても「アプリ開発環境は Windows 機 + WSL2 でいいんじゃないか?」と思える状況になってきました。スペック面での不安がないわけじゃないけど、環境的な意味では「時は来た」かな、と。

というわけで、自分の WSL 環境を WSL2 環境へ移行することにしました。以下その手順を備忘録として残しておきます。


【Hyper-V を有効化】
まず Windows の Hyper-V を有効化する必要があります。既に Hyper-V が有効になっている環境であればこの手順は不要ですが、今回はここも含めて紹介します。

その手順で利用するため Windows で PowerShell を起動します。この際に管理者権限で起動しておくようにします(バージョン確認だけなら管理者権限は不要ですが、WSL を WSL2 に変更する際に管理者権限が必要になります)。

そして以下のコマンドを実行します:
> Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

そしてこのコマンドを実行後に再起動をかけると Hyper-V が有効化されます。ここから以下の作業は再起動後に行ってください。


(↓2020/11/22 追記)
【Windows ハイパーバイザープラットフォームの有効化】
VirtualBox など、他のハイパーバイザー環境との共存のための機能を有効にします。

Windowsの機能の有効化または無効化から Windows ハイパーバイザープラットフォームを選択して、チェックを入れて OK をクリックします:
2020112201
(↑2020/11/22 追記)


【WSL のバージョンを確認】
ここから下の PowerShell での操作については(管理者権限の)コマンドプロンプトでも構いません。

Hyper-V を有効にして再起動後、まず現在利用中の WSL のバージョン(1のはず)を確認しておきます。PowerShell で以下のコマンドを実行します:
> wsl --list --verbose

すると以下のような結果になり、WSL(1) を使っていることが確認できます:
2020112101


【WSL の Linux カーネルを更新】
この WSL を WSL2 に変更するのですが、その前に WSL の Linux カーネルを最新版に更新しておきます。

まず以下へアクセスします:
https://docs.microsoft.com/ja-jp/windows/wsl/wsl2-kernel


「最新の WSL2 Linux カーネル更新プログラムパッケージをダウンロード」と書かれたリンクから更新パッケージをダウンロードします:
2020112102


ダウンロード後に実行して、WSL の Linux カーネルを更新します:
2020112103


【WSL を WSL2 に変更】
ここまでの準備ができていれば WSL を WSL2 に変更する準備が整いました。管理者権限の PowerShell で以下を実行して、まずは WSL のデフォルトバージョンを 2 に変更します(一瞬で終わります):
> wsl --set-default-version 2

続けて以下のコマンドも実行し、現在 WSL で動作中の Ubuntu 18.04 を WSL2 に変更します(少し時間がかかります):
> wsl --set-version Ubuntu-18.04 2

2020112101


これで WSL2 になった、はず。。


【WSL のバージョンを再確認】
最後に WSL のバージョンが2になっていることを確認します。再度先程と同じコマンドを実行し、バージョンが更新されていることを確認します:
> wsl --list --verbose

2020112102


WSL1 から WSL2 への環境移行に成功しました。

この記事の続きです。PayPay API を自分のアプリケーションで使うための準備やサンプルコード、使い方などはこちらを参照してください:
PayPay の API でアプリケーションに日本円での決済機能を実装する

こちらのエントリでは応用編というか、実際のアプリケーションの中で PayPay API を使って決済する際に意識することになるであろう事柄3点について考慮すべきポイントを紹介します。


1 作成した QR コードで実際に決済されたかどうかをアプリケーションから知る方法

前回の記事では簡単にウェブアプリケーションに PayPay による決済機能を組み込んで QR コードによる決済を実現することができる、という内容を紹介しました。ここまではよい、と。 ただ実際には QR コードを作成する所まではトラッキングできますが、作成した QR コードを使って決済が行われても、それは元のウェブアプリケーションの画面内で行われる決済ではないため「本当に決済までが行われた」のか、それとも「QRコードは表示されたけど、PayPay での決済は行われなかった」のかを識別する方法は別に考慮する必要があります。それをどうすればよいか、というのが実運用における最初のポイントです。

これは実は PayPay API 側で用意された機能を使うことで実現できます。前回の記事を参照いただくとわかるのですが、生成された QR コードを表示する際に以下のような JavaScript コードが実行されていました:
          :
          :
      success: function( result ){
        console.log( result );
        if( result && result.status && result.status == 201 && result.body && result.body.data ){
          var merchantPaymentId = result.body.data.merchantPaymentId; //. 支払いID(キャンセル時に必要)
          var codeId = result.body.data.codeId; //. QRコードID(QRコード削除時に必要)
          var url = result.body.data.url;  //. QRコードが表示されるページの URL

          if( url ){
            //. QRコードが表示されるページを別ウィンドウで開く
            window.open( url, 'PayPayWindow' );
          }
        }
      },
          :
          :

QR コードの表示は result オブジェクトの result.body.data.url の値を参照して、この値で示される URL を別ウィンドウで開くことで実現していました(別ウィンドウで開くため、これ以降の直接のトラッキングはできなくなっていました)。この時に取得できる result.body.data.merchantPaymentId という値を使って PayPay APIGetCodePaymentDetails 関数を実行すると、その QR コードのステータスを確認することができるのでした。ステータスを確認し、COMPLETED となっていればその決済は完了しており、そうでなければ完了していない、と判断できることになります。

より具体的にはこの merchantPaymentId をデータベースなどに保存しておいて、Webhook と使ったり、cron で定期的に確認したり、いずれも難しい環境下であっても例えば次回ログイン時などにステータスをチェックすることで決済の済/未済の判断ができるようになります。


2 作成した QR コードを「どのユーザーが」決済したかを判断する方法

1で QR コードが実際に決済されているかどうかを識別する方法を紹介しましたが、実運用においてはもう1点、その QR コードを「どのユーザーが」決済したのかを知る必要があります。これも決済そのものは簡単に実現してしまうのですが、別ウィンドウで開くページ内での決済のため、自分が作ったウェブアプリケーション内で決済ユーザーを識別するのが難しい、という問題を解決する必要があります。

こちらは少しコードを修正する必要がありますが可能です。現在のソースコードでは上述の merchantPaymentId をサーバーサイドで一意になるよう生成していますが、ここを変更し、クライアントサイドで「ユーザー名やユーザーIDを用いて merchantPaymentId を生成する(あるいはサーバーにユーザー ID を送信して、サーバーサイドでユーザー ID を用いた merchantPaymentId を生成する)ことで解決できそうです。つまり merchantPaymentId をただのランダムな文字列ではなく、(例えば頭にユーザーIDを付与するなどして)ここを見ることで誰が作成した QR コードなのかがわかれば、(1と合わせることで)誰が作成した QR コードが決済されたのか、も識別することができるようになります。


3 1回の QR コード決済で定期的な支払いをする方法

例えば月額課金のサブスクリプション型サービスと契約すると、毎月決まった額が引き落とされることになります。これを PayPay API の QR コード決済でも1回で実現できると、自分の作ったウェブアプリケーションのサブスク化ができるようになって便利だと思っています。

が、実はこの内容だけは現時点で実現の目処が立っていません。そもそも QR コードで分割払い契約って可能なんだろうか・・・

PayPay API や SDK のドキュメントも見ているのですが、なんとなく「現時点では未対応」なような気もしています。サブスクだと「解約」処理も必要になると思うのですが、そういう API も見当たらないような・・・ 今の時点においては毎月 QR コードを作って、その都度払ってもらう以外の方法はないのかもしれません(情報/アイデア求む)



というわけで、PayPay API を使うことでウェブアプリケーションに決済機能を簡単に付与することができるのですが、実運用までを意識すると、ここに挙げた3点についても考慮して設計・実装する必要があると思っています。ただ3番目の定期支払いはなんとか1回の処理で実現したり、それを途中で解約するような具体的な方法ないかなあ。。。

PayPay for Developers が公開され、アプリケーション開発者が自分のアプリケーション内に決済機能をもたせることが比較的容易にできるようになりました。これまでにも同様の機能はありましたが、PayPay アプリを利用した決済のため、クレジットカード情報など個人情報管理を意識することもなく、かつ日本円での決済ができるというメリット、加えて後述するようにその実装も非常にシンプルにできる点が画期的でした。

以下、実際に自分が Node.js で作成したサンプルを公開して紹介します。どの程度のシンプルさなのかも実際に見ていただきたいです。なお以下で紹介する内容は sandbox モードという、実際の決済は行わないテストモードで利用する想定で紹介しているので、安心して使ってみてください(アプリケーションはそのままで、加盟店登録を行って、モードを sandbox モードからプロダクションモードに変更することで本当の決済が行えるようになります)。

また API を細かく説明する前に、まずは実際に PayPay API を使ったサンプルアプリケーションを動かして決済を行い、その後でどのような実装になっているのかを説明します。

なお本稿は 2020/11/13 時点での動作を確認したアプリケーションに基づいて記載しています。


【準備】
サンプルを実際に動かすためにはいくつかの事前準備が必要です。まず何はともあれスマートフォンに PayPay アプリをインストールしておきましょう:
2020111301


次にローカル環境に Node.js をインストールしておきます。サンプルアプリケーションは Node.js で記述されているため、その実行環境としての Node.js を導入します。

そして PayPay for Developers に ID とサービス(実店舗に相当するアプリケーション)を登録する必要があります:
https://developer.paypay.ne.jp/account/signup

まずはメールアドレスとパスワードを指定して、ID を登録します:
2020111301


最初に指定したメールアドレスに確認のためのコードが送信されるので、メールを受信したらそこに書かれているコードを入力して「確認する」ボタンを押します。これでメールアドレスの存在を証明できました:
2020111301


次にサービスの内容を入力します。ここで入力した内容が決済時の画面などに表示されるものです。右上で skip することもできるようですが、ここでは登録する方法を紹介します:
2020111302


といってもここで指定するのはロゴの画像と、サービスの名称です。この例では Qdle という名前でサービスを登録しています(深い意味はありません、後で出てきます)。このあたりは適当に:
2020111303


次の画面では利用する決済手段を選ぶことができます。今回の例に限っては「ウェブペイメント」と「動的ユーザースキャン」なのですが、今後どういう使い方をするかわからないのでとりあえず全部チェックしました(最初からされています)。で「登録する」をクリック:
2020111304


無事にアカウントとサービスが PayPay for Developers に登録できました。「開始する」ボタンでダッシュボード画面に移動します:
2020111305


なお登録後はこちらのページから ID とパスワードでログインできます:
https://developer.paypay.ne.jp/account/signin

2020111302


ログイン直後のダッシュボード画面ではこのようなページが表示されます。本番モードではなく「テストモード」で稼働している点を確認してください(テストモード中は架空ユーザーでの決済になり、実際のお金の決済は行われません):
2020111302


画面下部に API キーシークレットが表示されています。また画面右上の DO と書かれた箇所をクリックすると MERCHANT ID を確認することができます。これら3つの値はこの後で使うことになるのでメモしておくか、コピー&ペーストできるようにしておきます:
2020111303


また後ほど sandbox モードで決済を行うのですが、その時に決済を行う架空ユーザー(3名)とそのパスワード、架空残高を画面下部の「テストユーザー」タブから確認することができます(パスワードの値はパスワード横のアイコンをクリックすることで見ることができます)。今はまだ使いませんが、この場所でユーザー情報を確認できることを覚えておきます:
2020111304


以上でサンプルアプリケーションを動かす準備はできました。


【ソースコードのダウンロードと編集】
次にサンプルソースコードをダウンロードします。git clone するか、ソースをまとめて zip ダウンロードして展開するなどしてソースコード一式を手元に用意します:
https://github.com/dotnsf/paypayapi

2020111305


展開されたファイルのうち、settings.js ファイルだけは動かす前に値の編集が必要です。テキストエディタでこのファイルを開き、以下の3行(テストモードでなく、本番モードで動かす場合は4行)を変更して保存します:
exports.apikey = '(API キーの値)';
exports.apisecret = '(シークレットの値)';
exports.merchantid = '(MERCHANT ID の値)';
exports.productionMode = false;   //. 本番モードの場合のみ true に変更

上3つは上述のダッシュボード画面で確認した値に変更します。また4行目はテストモードであれば false のままで、加盟店登録後に本番モードで稼働させる場合のみ true に変更します。

最後にこの状態で依存ライブラリをまとめてインストールします。コマンドラインやターミナルで paypayapi ソースコードフォルダに移動し、次のコマンドを実行します(実行完了までしばらく時間がかかります):
$ npm install

これでサンプルアプリケーションを動かすための準備ができました。

【アプリケーション起動】
まずはサンプルアプリケーションを動かします:
$ node app

そしてウェブブラウザで以下のアドレスを指定して開きます:
http://localhost:8080/

こんな感じのシンプルなページが表示されれば、アプリケーションの起動に成功です:
2020111306


画面には3つの機能しかなく、1つは支払額(円)を指定するフィールド、1つは支払い明細を記述するフィールド、もう1つは支払いを実行するボタンです。適当に入力してみます:

※下の例では支払額を 123 円、支払明細には「コーヒー代」と入力しました。
2020111307


この条件で PayPay による支払いを(架空ユーザーで)実行してみますが、テストモードで支払いを実行するために少し別の準備が必要になります。この状態のまま「支払い」ボタンを押さずに以下を続けます。

※ここで「支払い」ボタンを押して、以下の開発モードの切り替えに時間がかかってしまうと QR コードが無効になってしまい、スキャンできなくなってしまいます。その場合は改めてこの画面で「支払い」ボタンを押して QR コードを生成し直してください。


【PayPay 開発者モード】
支払いボタンを押す前にスマホ側の PayPay の準備をしておきます。スマホ側で PayPay を起動します。自分の(本物の)アカウントでログイン済みの場合はそのままでは架空ユーザーでの取引ができないので一旦ログアウトします。アカウントを選択し、アカウント情報画面の最下部からログアウトします:
2020111302

2020111303


改めて未ログイン状態で PayPay アプリを起動すると以下のようなログイン画面が表示されます。ここで PayPay アプリをテストモードに切り替えるため、画面左上の PayPay ロゴを7回タップします:
2020111304


途中からカウントダウンに・・・続けてロゴをタップします:
2020111305


すると「開発者モードでログイン」という選択肢が現れるので、これを選択します:
2020111306


開発者モードでのログイン画面が表示されます:
2020111307


ここでは自分のアカウントではなく、上述の PayPay for Developers ダッシュボード画面で確認したテストユーザーのいずれかの ID とパスワードを入力してログインします(ここでは下図一番上にいる 08075317593 ユーザーでログインしてみます):
2020111308


対象ユーザーのパスワード横にあるアイコンをクリックしてパスワードマスクを外すことで実際のパスワードを視認できるようになります。ユーザーネームとパスワードを入力して PayPay アプリに開発者モードでログインします:
2020111308


初回ログイン時のみ多要素認証が求められます。テストモードユーザーの SMS を受け取ることはできませんが、テストモードユーザーの認証コードは全て 1234 なので、1234 と入力します:
2020111309


開発者モードで、テストユーザーの ID でログインした時の画面です。上部に「開発者モードである」旨が表示されています:
2020111310



またこの状態で残高を確認してみます。ダッシュボードで確認した時と同じ残高(下図の場合は 99900 円)になっていることを確認します:
2020111311


これで PayPay をテストユーザーで使う準備ができました。普通の(本来の)モードに戻す場合はいったんログアウトし、再度正規のユーザーでログインしてください。


【アプリで生成した QR コードで決済】
PayPay アプリ側でテストユーザーの準備ができたので、改めて先程のアプリケーションに戻って、決済の続きを実行します。

支払額と明細を確認して「支払い」ボタンをクリックします:
2020111301


別ウィンドウが開き、その中に決済に関する情報と QR コードが表示されているはずです:
2020111302


この QR コードを開発者モードでログイン中の PayPay アプリを使ってスキャンします:
2020111301


すると(PayPay ユーザーにはおなじみの)「ペイペイッ」という音声が流れ、決済が完了してしまいます。普通に PayPay 使った時とまったく同じです:
2020111302


"Qdle" に支払った、という画面になっていますが、この "Qdle" は PayPay for Developers に最初に登録したサービス名です:
2020111303


残高を確認すると支払った分が引かれています。実決済ではないというだけで、本当に決済が実現してしまいました。。
2020111304


ダッシュボード側にも決済が反映されており、残高が更新されているはずです:
2020111303


開発者モードで実行されているため、実際に本当のお金の動きがあるわけではないのですが、このモードを変更した上で、実際の PayPay アプリで QR コードを読みとって決済すれば本当にお金が動く決済が実現します。

以下、このアプリケーションの中身(というか、このオペレーションに関わる部分)を抜粋して紹介しますが、いかにシンプルな作りになっているのかを確認できると思っています。


【ソースコード解説】
ではこの PayPay 決済アプリがどのようなソースコードで実現されているのかを解説します。といっても本当にシンプルなので、あまり解説するポイントもないのですが・・・

まずアプリ画面の HTML 部分です。本当にこれだけ、「支払い」ボタンの onClick イベントに反応して createQRCode() 関数を実行しているだけです:
<div class="container">
  <table class="table table-bordered">
    <tbody>
      <tr>
        <td>支払額(円)</td>
        <td><input type="text" id="amount" value="100"/></td>
      </tr>
      <tr>
        <td>明細</td>
        <td><input type="text" id="orderDescription" value="" placeholder="書籍代"/></td>
      </tr>
      <tr>
        <td> </td>
        <td><button class="btn btn-primary" id="orderBtn" onClick="createQRCode();">支払い</button></td>
      </tr>
    </tbody>
  </table>
</div>


次に「支払い」ボタンをクリックした時に実行されるハンドラ(createQRCode() 関数)の JavaScript がこちらです。支払額と明細の情報を送信して POST /paypay/qrcode の REST API を実行しているだけです。成功後の処理については後述します。ここまでは特に解説するほどの内容にはなっていません:
function createQRCode(){
  var _amount = $('#amount').val();
  var orderDescription = $('#orderDescription').val();
  
  var amount = ( _amount ? parseInt( _amount ) : 0 );
  orderDescription = ( orderDescription ? orderDescription : '' );
  if( amount ){
    $.ajax({
      type: 'post',
      url: '/paypay/qrcode',
      data: { amount: amount, orderDescription: orderDescription },
      success: function( result ){
        console.log( result );
          :
          :
      },
      error: function( e0, e1, e2 ){
        console.log( e0, e1, e2 );
      }
    });
  }else{
    alert( 'amount needed.' );
  }
}

次に REST API 側のコードを紹介します。REST API は paypay/paypay.js 内でまとめて実装していて、この中では最初に settings.js で指定された API キーやシークレット、MERCHANT ID の値を使ってPAYPAY オブジェクトの初期化をしています:
var settings = require( '../settings' );

var PAYPAY = require( '@paypayopa/paypayopa-sdk-node' );
PAYPAY.Configure({
  clientId: settings.apikey,
  clientSecret: settings.apisecret,
  merchantId: settings.merchantid,
  productionMode: settings.productionMode
});

そして POST /paypay/qrcode の中身がこちらです。PayPay SDK を使って PAYPAY.QRCodeCreate という関数を実行しています。実行時のパラメータ(payload)を指定していますが、決済額の情報は amount オブジェクトで指定しています( currency を "JPY" に指定していますが、現状はこの値しか使えないようです)。また merchantPaymentId をランダムに生成して指定していますが、ここで指定した値は後にキャンセルする際に必要になるので、アプリケーションによってはどこかで保持しておく必要があるかもしれません。また orderDescription に明細情報の文字列を入れておくことで決済時の画面にもコメントを表示させることが可能になります。

この PAYPAY.QRCodeCreate 関数は成功するとステータスコードが 201 になります。その値を見て成功・失敗を判断し、application/json 形式で結果を返しています:
router.post( '/qrcode', function( req, res ){
  res.contentType( 'application/json; charset=utf-8' );

  if( req.body.amount ){
    var payload = {
      merchantPaymentId: generateId( 'dotnsf-paypay' ),
      amount: { amount: req.body.amount, currency: "JPY" },
      codeType: "ORDER_QR",
      orderDescription: ( req.body.orderDescription ? req.body.orderDescription : 'orderDescription' ),
      isAuthorization: false,
      redirectUrl: "https://paypay.ne.jp/",
      redirectType: "WEB_LINK",
      userAgent: ( req.body.userAgent ? req.body.userAgent : 'My PayPay App/1.0' )
    };
    PAYPAY.QRCodeCreate( payload, function( response ){
      //console.log( response );
      if( response.STATUS && response.STATUS >= 200 && response.STATUS < 300 ){   //. 実際は 201
        res.write( JSON.stringify( { status: response.STATUS, body: JSON.parse( response.BODY ) } ) );
        res.end();
      }else{
        res.status( response.STATUS );
        res.write( JSON.stringify( { status: response.STATUS, body: JSON.parse( response.BODY ) } ) );
        res.end();
      }
    });
  }else{
    res.status( 400 );
    res.write( JSON.stringify( { status: 400, error: 'no amount info found.' } ) );
    res.end();
  }
});


ここも PayPay SDK を使っているだけで、それほど複雑な内容ではないと思っています。そして改めて1つ前の「支払い」ボタンをクリックした時のハンドラの成功後の処理がこちらです:
          :
          :
      success: function( result ){
        console.log( result );
        if( result && result.status && result.status == 201 && result.body && result.body.data ){
          var merchantPaymentId = result.body.data.merchantPaymentId; //. 支払いID(キャンセル時に必要)
          var codeId = result.body.data.codeId; //. QRコードID(QRコード削除時に必要)
          var url = result.body.data.url;  //. QRコードが表示されるページの URL

          if( url ){
            //. QRコードが表示されるページを別ウィンドウで開く
            window.open( url, 'PayPayWindow' );
          }
        }
      },
          :
          :


REST API の実行結果として返ってきたオブジェクト(result)を使い、result.body.data.url の値を取得します。この値が送信した条件で決済(より正確には決済して、自分が登録した店舗に決済額が入金される仕組みまで含めた処理を実行)するための QR コードが表示されるページの URL となっています。なので window.open() を使い、別ウィンドウで同ページを表示する、という処理を行っています。

別ウィンドウで表示されるページは上述しました。ここに表示される QR コードを PayPay アプリで読みとり、後は PayPay とそのアプリが面倒みてくれます。なのでサンプルアプリとしては何もしていません。

QR コード決済のエラー処理や例外対応については省略してしまっていますが、本質的にはたったこれだけのコードで自分のアプリケーションに日本円での PayPay 決済処理が実装できてしまう、という事実に驚いてしまいました。


【使ってみた感想】
なんといっても非常に簡単に実装できてしまうことに驚きでした。クレジットカード情報(の保管)を意識する必要もなく、日本円でのオンライン決済アプリのハードルがかなり下がったんじゃないかと感じました。これから決済アプリが流行る要因にもなりうると思っています。

このサンプリアプリケーションのソースコードを公開しているので、興味ある方は中を見ていただきたいです。実際にはキャンセル処理への対応ができるような REST API も実装済みではありますが、本サンプルアプリ内では使っていません。なので、本当にシンプルなコードだけでここまでできてしまい、かつアプリケーション側が意識すべきセキュリティ要件もかなり低く作れそうな印象を持っています。


【参考リンク】
Node.js 用 PayPay SDK
PayPay for Developers 公式ドキュメント
ダイナミック QR コード解説


【応用編】
なお、このブログエントリの続きはこちら。実運用を意識した内容の応用編です:
http://dotnsf.blog.jp/archives/1078272938.html

ウェブアプリケーションで QR コードを表示したくなることがあります。スマホを持っている人にその場でとあるURLにアクセスしてもらったり、文字列などの情報を送るのに便利な方法だと思っています。

そんな機能が必要な場合、自分は jquery.qrcode.js を使っています。ブラウザの JavaScript(jQuery)だけで文字列の QR コードを簡単に生成することができます。サンプルページを用意したので、こちらで試すとわかりやすいと思います:
https://dotnsf.github.io/jquery_qrcode/

2020110601


画面最上部のテキストフィールドに URL や文字列を入力し、青いボタンを押すと入力した文字列から QR コードを生成して表示する、というものです。この部分は以下のようなコードで実現しています:
  :

<script src="./qrcode.min.js"></script>

  :

<div class="container">
  <input type="text" id="text" value=""/><button class="btn btn-primary" onClick="generateQRCode();">QRコード</button>
</div>

<canvas id="qrcode"></canvas>

<script>
var text = '';


function generateQRCode(){
  $('#qrcoe').html( '' );
  text = $('#text').val();
  if( text ){
    QRCode.toCanvas( document.getElementById( 'qrcode' ), text, function( err ){
      if( err ){
        console.log( err );
      }
    });
  }
}

  :

まず QR コードを描画するための <canvas> タグ(id="qrcode")を用意します。そしてボタンがクリックされるとテキストフィールドの値を取り出し、<canvas> の id を指定して QRCode を描画する、というシンプルなものです。これだけで QR コード化が実現できます。

文字列や URL を読み取らせたい対象者がスマートフォンユーザーだけであればこれだけで最小限必要な機能は実現できます。問題は対象者の中に PC ユーザーがいて、PC ユーザーにもこの URL や文字列を提供したい場合です。PC からは QR コードを読み取れない人が多数だと思うので直接メッセンジャーやメールなどで文字列や URL を送ればいいのですが、では逆に QR コードで表示されている文字列を取り出す便利な方法はないでしょうか? 上記サンプルの場合は QR コード化する文字列をテキストフィールドに指定しているのでテキストフィールドから取り出せばいいのですが、そういうケースばかりではありません。 以下は「QR コード部分をクリックした時に、その文字列をクリックボードにコピーする」ためのコードを加えました。これによってクリップボードからペーストするだけでメッセンジャー等で送れるようになり、UI的にも楽だと思ったのでした。 加えて、QR コード部分をクリックした際に「クリック感」というか「押された感」が出るような、一瞬だけ影ができるような視覚効果を加えてみました。

最終的なコードはこのようになりました:
  :
<script src="./qrcode.min.js"></script>

<style type="text/css">
html, body{
  text-align: center;
  background-color: #fafafa;
  font-size: 20px;
  color: #333;
}
#qrcode:active{
  border: 1px solid #334c66;
  background-color: #69c;
  -webkit-box-shadow:inset 0px 0px 8px #334c66;
  -moz-box-shadow: inset 0px 0px 2px #3a6da0;
  box-shadow: 0px 0px 2px #3a6da0;
}
</style>
</head>
<body>

<div class="container">
  <input type="text" id="text" value=""/><button class="btn btn-primary" onClick="generateQRCode();">QRコード</button>
</div>

<canvas id="qrcode"></canvas>

<script>
var text = '';

$(function(){
  $('#qrcode').on( 'click', function( e ){
    copyClipboard( text );
  });
});

function generateQRCode(){
  $('#qrcoe').html( '' );
  text = $('#text').val();
  if( text ){
    QRCode.toCanvas( document.getElementById( 'qrcode' ), text, function( err ){
      if( err ){
        console.log( err );
      }
    });
  }
}

function copyClipboard( str ){
  //. 空 div と空 pre
  var tmp = document.createElement( 'div' );
  var pre = document.createElement( 'pre' );

  pre.style.webkitUserSelect = 'auto';
  pre.style.userSelect = 'auto';
  tmp.appendChild( pre ).textContent = str;

  //. 画面外へ
  var s = tmp.style;
  s.position = 'fixed';
  s.right = '200%';

  //. body に追加
  document.body.appendChild( tmp );
  document.getSelection().selectAllChildren( tmp );

  //. クリップボードにコピー
  var result = document.execCommand( "copy" );

  //. 要素削除
  document.body.removeChild( tmp );

  return result;
}
</script>

  :

QR コード化したテキストの内容を変数 text に保存しておき、id="qrcode" のキャンバスがクリックされた時に text の値をクリップボードにコピーする、という内容を加えています。また視覚効果としてクリックされた時だけ有効になる #qrcode:active 要素を定義し、影をつけるなど見た目に変化を加えています。


このページのトップヘ