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 に次のように設定を追加します。

<platform name="ios">
    :
  <config-file platform="ios" parent="LSApplicationQueriesSchemes" target="*-Info.plist">
    <array>
      <string>square-commerce-v1</string>
    </array>
  </config-file>
</platform>

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

準備

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

// Square APIのアプリケーションID
var client_id = 'YOUR_SQUARE_APPLICATION_ID';

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

// カスタムURLスキーマ
var schema = 'YOUR_CUSTOM_SCHEMA://';

アプリの画面

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

<ons-page id="helloworld-page">
  <ons-toolbar>
    <div class="center">Square APIデモ</div>
  </ons-toolbar>
  <p>
    <ons-button modifier="large" id="square">100円支払う</ons-button>
  </p>
  <p>
    <ons-list>
      <ons-list-header>結果</ons-list-header>
      <pre id="result">
      </pre>
    </ons-list>
  </p>
</ons-page>

JavaScriptの処理

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

// 100円支払うボタンを押した時の処理
$('#square').on('click', function(e) {
  // パラメータの設定

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

  // URLを開く
});

パラメータの設定

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

// パラメータの設定
var dataParameter = {
  // 決済額です。amountが数値、currency_codeが通貨単位になります。
  // 今回は100円です。
  "amount_money": {
    "amount" : "100",
    "currency_code" : "JPY"
  },
  // コールバックを受け取るURLです。カスタムURLスキーマをそのまま呼び出します。
  "callback_url" : schema,
  // SquareのAPIで指定されるアプリケーションIDを指定します。
  "client_id" : client_id,
  // バージョンは1.3固定です。
  "version": "1.3",
  // 取引のメモです。任意の文字です。
  "notes": "notes for the transaction",
  // オプションです
  "options" : {
    // 決済種別です。今回はクレジットカード、現金、その他を指定しています。
    "supported_tender_types" : [
      "CREDIT_CARD",
      "CASH",
      "OTHER"
    ]
  }
};

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

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

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

// レジアプリを呼び出すURLです
var url = "square-commerce-v1://payment/create?data=" + encodeURIComponent(JSON.stringify(dataParameter));

URLを開く

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

// URLを開きます
location.href = url;

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

決済後のコールバック

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

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

// カスタムURLスキーマからアプリを開いた際に呼ばれる関数です
function handleOpenURL(url) {
  setTimeout(function() {
    var param = JSON.parse(decodeURIComponent(url.replace(schema, '').replace('?data=', '')));
    $('#result').html(`
      結果ID : ${param.status}
      トランザクションID : ${param.transaction_id}
      クライアントトランザクションID : ${param.client_transaction_id}
    `);
  }, 0);
}

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

{
  status: 'ok',
  transaction_id: 'aaa...aaa',
  client_transaction_id: 'bbb...bbb'
}

決済が問題なく行われた場合、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にアップロードしてあります。実装時の参考にしてください。