Square Point of Sale APIのiOSアプリ導入手順

[POINT OF SALE API / Build with iOS](https://developer.squareup.com/docs/pos-api/build-on-ios#step-8-test-your-code) のドキュメントを日本語化しました（2019/11/14）


## Point of Sale APIとは
- Point of Sale APIはカスタムモバイルアプリケーションからSquare Point of Saleアプリを開いて、Squareハードウェアを使用して直接支払いを処理する決済のことをさします。

## 詳細
- POS APIを使用すると、モバイルアプリケーションでSquare Point of Saleアプリを開いて、Squareハードウェアを使用して直接支払いを処理できます。 
- 開発者は、Point of Sale APIを使用して、ハードウェア統合について心配することなく、カスタマイズされた販売時点情報管理ソリューションまたは支払いが必要なその他のアプリケーションを構築できます。 Squareは、PCI準拠を維持するという負担を負います
- チェックリスト、評価、または監査は不要です。
- POS APIは、iOSおよびAndroid上のネイティブアプリケーションおよびWebアプリケーションで利用できます。

## iOSアプリにSDKを追加する方法

### ステップ1：Square Point of Saleアプリをインストールする
App StoreからSquare Point of Saleアプリの最新バージョンをインストールして、iOS用POSの最新バージョンで使用することをお勧めします。

POSアプリのインストール済みバージョンを確認するには：

1. POSアプリを開く
2. [ヘルプ]> [サポート]に移動します。
3. サポート画面の一番下までスクロールします。

Point of Sale SDKの古いバージョンを使用する必要がある場合、Point of Saleアプリの互換バージョンをインストールする必要があります。

### ステップ2：アプリケーションを登録する
iOS向けSquare Point of Saleアプリは、リクエストのソースを認証できる場合にのみリクエストを受け入れます。 Squareは、次を使用してアプリケーションリクエストを認証します。

- アプリバンドルID — Square Point of Saleアプリは、アプリのバンドルIDを使用して、着信リクエストのソースを検証します。
- アプリURLスキーム（myapp-url-schemeなど）。 指定するURLスキームは、アプリケーションのInfo.plistファイルのCFBundleURLSchemes属性と一致する必要があります。

アプリケーションを登録するには：

1. アプリケーションダッシュボードでアプリケーションの設定のPOS APIタブに移動します。
2. [iOS]セクションで、アプリのバンドルIDとURLスキームを入力します。
3. 「保存」をクリックします。

### ステップ3：Square Point of Sale SDKをプロジェクトに追加する

CarthageプロジェクトにPOS SDKを追加します
- Carthageを使用して依存関係を管理する場合、次のシェルコマンドを使用してPoint of Sale SDKをインストールします。

`github "Square / SquarePointOfSaleSDK-iOS"`

### ステップ4：URLスキームを追加する
URLスキームをsquare-commerce-v1として設定し、カスタム応答URLスキームを設定します。

Info.plistファイルにLSApplicationQueriesSchemesキーとしてリクエストURLスキームを追加して、アプリがsquare-commerce-v1 URLスキームを使用してSquare Point of Saleを開くことを示します。

```
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>square-commerce-v1</string>
</array>
```

Info.plistファイルにCFBundleURLTypesキーとしてカスタム応答URLスキームを追加します。

```
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>YOUR_BUNDLE_URL_NAME</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp-url-scheme</string>
    </array>
  </dict>
</array>
```

### ステップ5：アプリから支払いを開始するコードを追加します
支払いの詳細を含むSCCAPIRequestオブジェクトを作成します。

```
import Foundation

// Replace with your app's callback URL as set in the 
// Square ApplicationDashboard [https://connect.squareup.com/apps]
// You must also declare this URL scheme in <#YOUR_PROJECT#>.plist, 
// under URL types.
let yourCallbackURL = URL(string: "hellocharge://callback")!


// Specify the amount of money to charge.
var amount: SCCMoney?
do {
    amount = try SCCMoney(amountCents: 100, currencyCode: "USD")
} catch {}

// Your client ID is the same as your Square Application ID.
// Note: You only need to set your client ID once, before creating your first request.
SCCAPIRequest.clientID = YOUR_CLIENT_ID

var request: SCCAPIRequest?
do {
    request = try SCCAPIRequest(callbackURL: callbackURL,
                                amount: amount,
                                userInfoString: nil,
                                merchantID: nil,
                                notes: "Coffee",
                                customerID: nil,
                                supportedTenderTypes: SCCAPIRequestTenderTypeAll,
                                clearsDefaultFees: false,
                                returnAutomaticallyAfterPayment: false)
} catch {}
```

### ステップ6：トランザクションをSquare Point of Saleアプリに送信するコードを追加します
SCCAPIConnectionクラスを使用して、SCCAPIRequestをSquare Point of Saleアプリに送信します。

```
var success = false
do {
    try SCCAPIConnection.performRequest(request)
    success = true
} catch {}
```

### ステップ7：Square Point of Saleアプリからデータを受信するためのコードを追加します
- Square Point of Saleアプリから結果を受け取り、それで何かをするためのコードを追加する必要があります。 
- 次のサンプルコードは、UIApplicationDelegateに `application：openURL：options：` メソッドを実装して、結果を受け取ります。 
- トランザクションが成功した場合、サンプルコードは新しく作成されたチェックアウトオブジェクトを印刷し、そうでない場合はエラーの説明を印刷します。

```
func application(
    _: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
    let sourceApplication = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String
    // Make sure the URL comes from Square Point of Sale; fail if it doesn't.
    if !(sourceApplication?.hasPrefix("com.squareup.square") ?? false) {
        return false
    }

    // The response data is encoded in the URL and can be decoded as an SCCAPIResponse.
    var decodeError: Error?
    SCCAPIResponse
    let response = SCCAPIResponse(responseURL: url, error: &decodeError)

    if response.isSuccessResponse {
        // Print checkout object
        print("Transaction successful: \(response)")
    } else if decodeError != nil {
        // Print decode error
        if let decodeError = decodeError {
            print("Decode Error: \(decodeError)")
        }
    } else {
        // Print the error code
        print("Request failed: \(response.error)")
    }

    return true
}
```

#### 重要
アプリケーションは、Point of Sale APIリクエストが発行されたかどうか、およびコールバックが受信されたかどうかを追跡する必要があります。 アプリ切り替えAPIの制約により、マーチャントはAPIリクエスト中にSquare Point of Saleを離れてアプリに戻る場合があり、Squareに戻ってトランザクションを完了するように指示するのはお客様の責任です。

### ステップ8：コードをテストする
- 支払いの受け取りに使用するビジネス拠点でSquare Point of Saleアプリにログインします。
- アプリを開き、トランザクションを開始します。
- コールバックをテストします。
  - キャンセルコールバックのテスト：トランザクションをキャンセルします
  - 成功コールバックのテスト：成功コールバックを受信するには、現金取引を完了します。

v2 Sandbox（ベータ版）は、モバイルのクレジットカードテストをサポートしていません。 本番環境のクレジットカードでテストするには、Square Readerを接続し、小額のカード支払い（最低1 USD）を処理してから、Square Point of Saleから払い戻しを発行します。 開発中のアプリをテストするには、モバイルでのテストに関する推奨事項をご覧ください。