Square

必要なもの

各フィールドを尋ねる理由

Access token

チェックアウトリンクの作成を承認し、請求があなたのアカウントを通るようにします。

Webhook signature key

届いた webhook が本当に Square からのものだと証明し、誰も「支払い済み」イベントを偽造できないようにします。access token とは別の値です。

Location ID

どのロケーションがお金を受け取るかを Square に伝え、チェックアウトの通貨を設定します。秘密ではありません。

成功とキャンセルの URL

素の設定です。支払い後、または引き返した後に購入者がたどり着く先。秘密ではありません。

設定

1. Square 開発者ダッシュボードを開く

   developer.squareup.com にサインインします。各アプリケーションは独自の認証情報を持ち、テスト用の無料 Sandbox が一緒に作成されます。このガイドでは Sandbox を使って説明しますが、Live の手順も同じで、Sandbox / Production トグルを切り替えて本番の認証情報を使うだけです。新しいアプリを作るには、Applications 画面の「+」タイルをクリックします。

   ⤢
2. アプリケーションに名前をつける

   アプリケーションに分かりやすい名前(例:「Coin Moebius」)を付けて「Next」をクリックします。

   ⤢
3. アクセストークンをコピーする

   アプリを開き、Credentials に移動します。上部の Sandbox / Production トグルが設定しようとしている環境と一致していることを確認します。Access token の隣のコピーアイコンをクリックして控えておきます。

   ⤢

   アクセストークンは秘密です。パスワードと同様に扱ってください。Sandbox と Production はそれぞれ別のトークンを持つので、混同しないでください。

4. Location ID をコピーする

   左メニューで Locations を開きます。支払いを受け取るロケーションの Location ID をコピーします。チェックアウトの通貨を設定するので、使用したい通貨のロケーションを選んでください。

   ⤢
5. Webhooks → Subscriptions を開く

   Square では webhook エンドポイントを「subscription(購読)」と呼びます。左メニューで Webhooks を展開し、Subscriptions を開いて「Add subscription」をクリックします。

   ⤢
6. サブスクリプションを追加してイベントを選ぶ

   名前を付け(例:「coin-moebius」)、Notification URL にプロジェクトの Square webhook アドレス(下記)を貼り付けます。次に Events で Coin Moebius が使うイベントを検索してチェックし、「Save」をクリックします。

   • 一回払い:payment.created、payment.updated、refund.created、refund.updated、dispute.created、dispute.state.updated。
   • サブスクリプション(販売している場合のみ):subscription.created、subscription.updated、subscription.canceled、subscription.deactivated、invoice.payment_made、invoice.scheduled_charge_failed。定期課金をしない場合は省略してください。

   https://api.coinmoebius.com/webhook/square/<your project id>

   ⤢

   プロジェクト ID は Coin Moebius ダッシュボードのプロジェクト名の下にあります。上記のアドレスに入れてください。余分なイベントは無害です。使用しないものは無視されます。接続済みプロバイダーカード(最後のステップ)にも同じ URL が参照用に表示されます。

7. 作成したサブスクリプションを開く

   Square はサブスクリプションを保存し、ステータス「Enabled」で Webhooks 一覧に表示します。名前をクリックして、署名キーがある詳細パネルを開きます。

   ⤢
8. Signature key をコピーする

   サブスクリプションの Properties パネルで、Signature key の隣のコピーアイコンをクリックします。これは Coin Moebius が各 webhook が本当に Square から来たことを確認するために使う値です。サブスクリプション作成後にのみ存在するため、接続ステップの前に webhook を設定しました。

   ⤢
9. Coin Moebius に戻る:プロバイダーを追加 → Square

   プロジェクトで Providers タブを開き、「プロバイダーを追加」をクリックし、「サービスをつなぐ」を選んで Square を選びます。Success URL と Cancel URL を設定します。Live タブで Access token、Webhook signature key、Location ID を貼り付けて「保存」をクリックします。最初にサンドボックスの認証情報で設定する場合は、代わりに Test タブに貼り付け、後から Edit でライブの認証情報を追加します。

   ⤢
10. 接続しました

    Square が Providers タブに接続日と共に表示されます。カードには Square に貼り付けたのと同じ webhook URL、編集、接続解除が表示されます。テストモードのトグルを使って、本番公開前にサンドボックスの注文を端から端まで通すことができます。

    ⤢

    サンドボックスのカードは実際のカードに請求することはありません。カード番号 4111 1111 1111 1111、CVV 111、任意の未来の有効期限、任意の有効な郵便番号(例:94103)を使ってください。

接続した後

本番公開の前に、テスト支払いを一度実行します。

1. 商品を作り、その Environment を Testing に設定します。これで商品がサンドボックスの認証情報で動き、お金を動かさずに注文を一通り出せます。(サンドボックスの組を省いた場合、Testing の商品はライブに戻るので、先に追加してください。)
2. プロジェクトに向けた買うボタンをページ(ローカルの HTML ファイルでも可)に置きます。
3. 上記のサンドボックスのテストカードでチェックアウトを完了します。
4. 取引タブを開きます。Testing と付いた新しい行が現れます。そのステータスが succeeded に達したら、認証情報と webhook が両方とも端から端まで機能しています。

実際の支払いの準備ができたら、商品の Environment を Live に切り替えます。

トラブルシューティング

まず「検証」から。ダッシュボードで「検証」(または「テスト認証情報を検証」)をクリックして、access token とロケーションを確認します。

検証が失敗する。

access token と Location ID を改めてコピーしてください。Production と Sandbox は別のトークンを持つので、混ぜないでください。

署名の検証が失敗する、または注文が保留のまま。

Square は正確な通知 URL と本文に対して署名します。Square に登録する URL は、末尾のスラッシュも余分なクエリ文字列も無く、あなたの webhook URL と一字一句一致しなければなりません。その後、同じエンドポイントから signature key を改めてコピーしてください。

端から端まで確認する。

Square Developer Console → Webhooks → あなたの subscription → Send Test Event、その後注文が更新されるのを見てください。

知っておくとよいこと

通貨はロケーションに従う. チェックアウトは、提供した id のロケーションの通貨で請求します。

シークレットのローテーション. access token や signature key はいつでもローテーションでき、新しい値を貼り付けます。秘密のフィールドは編集時に空欄のままです。

ご質問は? Join our Discord