Squareは、専用のカードリーダーを使ってスマホやタブレットでカード決済が利用できるサービスです。決済手数料以外のコストがかからず手軽に利用できるため、カフェや雑貨屋など様々なお店で使われています。
利用を開始するには、イヤホンジャックに挿すタイプのカードリーダーを入手し、「Square POSレジ」を端末にインストールします。このアプリはカスタムURLスキーマやインテントを使って他のアプリと連携できるようになっています。

今回はMonacaと「Square POSレジ」アプリの連携方法をご紹介します。現在AndroidではSquareとの連携ができないため、プラットフォームはiOSを対象とします。

連携の仕組み

iOSで外部アプリと連携する場合にはカスタムURLスキーマを使うケースが多いです。「Square POSレジ」アプリには square-commerce-v1:// というURLスキーマが設定されています。これを location.href に対して適用すると「Square POSレジ」を起動できます。

決済処理が終わった後は逆に「Square POSレジ」アプリからMonacaアプリが呼び出されます。そのため、MonacaアプリにもカスタムURLスキーマを実装しておかなければなりません。今回は squaresample:// というURLスキーマを設定することにします。
この設定は、 Custom-URL-scheme というプラグインで実現できます。

Squareの設定

まず最初にSquareにユーザ登録を行います。実際の利用に際しては銀行口座などの情報が必須になります。

登録が終わったら開発者ポータルにログインします。

最初にアプリケーションを作ります。

アプリケーションを作った時に生成されるアプリケーションIDを後で使いますので覚えておいてください。
なお、「Square POSレジ」アプリはSandbox(実際にお金を動かさずに実行できるテスト環境)に対応していませんので注意してください。

「Point of Sale API」タブに移動してiOSのバンドルID(App ID)と、MonacaアプリのカスタムURLスキーマ(squaresample)を入力します。

これで準備完了です。

サンプルアプリの説明

今回作るアプリの流れです。まず最初に画面が表示されます。

100円支払うボタンをタップすると、「Square POSレジ」アプリに遷移します。

今回は現金を使いますが、クレジットカード払いもできます。

決済が完了しました。

決済が終わるとMonacaアプリに処理が戻ってきて、決済に関する情報が受け取れます。

プラグインの設定

Monacaプロジェクトを作ったらCordovaプラグインをインストールします。今回は二つのプラグインが必要です。

Custom-URL-scheme

Custom-URL-scheme

MonacaアプリにURLスキーマを実装するプラグインです。Cordovaプラグインの設定で URL_SCHEME=squaresample といった形で指定します。この記述の場合、 squaresample:// で外部(今回は「Square POSレジ」アプリ)からMonacaアプリを呼び出せるようになります。

cordova-plugin-queries-schemes

cordova-plugin-queries-schemes

こちらは逆にMonacaアプリから実行できるカスタムURLスキーマを指定するプラグインです。iOSではセキュリティ上の理由で実行できるカスタムURLスキーマが制限されています。このプラグインを導入することで、実行可能なカスタムURLスキーマを追加できます。

プラグインをインストールしたら config.xml に次のように設定を追加します。

この記述により、Monacaアプリから「Square POSレジ」アプリを square-commerce-v1:// のように指定して呼び出すことができるようになります。

準備

まず最初にSquareで取得したアプリケーションIDを設定します。 js/app.js の上の方にあります。

また、MonacaアプリのカスタムURLスキーマも設定します。
YOUR_CUSTOM_SCHEMA を squaresample に書き換えてください。

アプリの画面

画面は必要最小限のシンプルな形にしています。「100円支払う」ボタンを押すと「Square POSレジ」アプリが立ち上がって、決済が終わると同じ画面に戻ってきます。

JavaScriptの処理

「100円支払う」ボタンを押した時の処理を作ります。

パラメータの設定

レジアプリに渡すパラメータを設定します。一つ一つのパラメータの詳細についてはコメントを参考にしてください。

決済種別の supported_tender_types は上記の他、SQUARE_GIFT_CARD(ギフトカード)やCARD_ON_FILE(定期購読用に登録しているカード情報を使用)も指定できます。

レジアプリを開くURLの設定

上述の設定値をJSON文字列にしてエンコードし、それをdataパラメータとして square-commerce-v1://payment/create に渡します。

URLを開く

準備ができましたのでURLを開きます。

これで「Square POSレジ」アプリが立ち上がります。

決済後のコールバック

決済が完了したら指定したURLスキーマ(squaresample://)に対してコールバックされます。
Custom-URL-scheme プラグインでは、コールバックされた時に handleOpenURL という関数が呼び出されるようになっています。

この時、コールバック後すぐに処理を行うとうまく動かない場合があります。そのため setTimeout() でラップしています。

「Square POSレジ」アプリを開いた時と同様にdataパラメータに結果のJSONが送られてきます。デコードして JSON.parse() すれば結果が取り出せます。iOSの場合は次の3つの結果情報が渡されます。

決済が問題なく行われた場合、status は常にokという文字になります。 transaction_id はサーバ側の取引IDになります。 client_transaction_id はクライアント側の取引IDで、オフライン決済(現金含む)を行った際に使われるものになります。

以上で完成です。
なお、このアプリはサードパーティ製のCordovaプラグインを利用していますので、Monaca Proプラン以上のアカウントが必要です。
また、ストア版のMonacaデバッガーでは動作検証できません。サードパーティ製Cordovaプラグインを含む、カスタムビルドデバッガーを端末にインストールしたうえで実行してください。


このように実装することでMonacaアプリと「Square POSレジ」アプリを連携することができます。各店舗向けに「Square POSレジ」アプリのUIをカスタマイズしたいといった場面でMonacaを活用頂くと良いのではないでしょうか。

今回のコードはgoofmint/Square_Monaca_POS_API_Demoにアップロードしてあります。実装時の参考にしてください。