決済されたタイミングでシステムに通知して欲しいと思うことはないでしょうか。それを実現できるのがSquareのWebhooks APIです。他にもタイムカードが更新されたタイミングでも通知を受けられます。
今回はサンプルコードをベースに、Webhooks APIの使い方を紹介します。
設定について
Webhooksの設定はSquare Developer PortalのWebhooksタブにて行います。Webhooksを有効にして、URLを指定します。これはPOSTで呼ばれるURLを指定します。
URLを設定すると、Signature Keyが生成されます。通知先のURLと共に使いますので覚えておきます。
リクエストの検証を行う
WebhooksはPOSTリクエストで呼ばれます。そしてまず必要なのがリクエストの検証です。使うのはリクエストのボディとHTTP_X_SQUARE_SIGNATUREヘッダーです。以下はRubyのコード例です。
callback_body = request.body.string
callback_signature = request.env['HTTP_X_SQUARE_SIGNATURE']
ここに先ほど設定したWebhooksのURL（WEBHOOK_URL）とSignature Key（WEBHOOK_SIGNATURE_KEY）を使って検証を行います。
string_to_sign = WEBHOOK_URL + callback_body
string_signature = Base64.strict_encode64(OpenSSL::HMAC.digest('sha1', WEBHOOK_SIGNATURE_KEY, string_to_sign))
Digest::SHA1.base64digest(string_signature) == Digest::SHA1.base64digest(callback_signature)
# trueなら検証OK
検証した結果が正しければ問題ありません。
JSONの内容を取得
内容が問題なければリクエストをJSONにします。
callback_body_json = JSON.parse(callback_body)
入っている内容は次のようになります。
{
"location_id": "AAABCHDD",
"merchant_id": "JGHJ0343",
"event_type": "PAYMENT_UPDATED",
"entity_id": "Jq74mCczmFXk1tC10GB"
}
entity_idは取引IDになります。location_idと組み合わせてSquare APIから取引の詳細情報を取り出せます。
# Square APIにアクセスして決済情報の詳細を取得します
api_instance = SquareConnect::V1TransactionsApi.new
response = api_instance.retrieve_payment(location_id, payment_id)
レスポンスとして、細かい取引情報が取得できます。以下はレスポンスの一部です。
{
:id=>"4867tampXm52hAvQ9To5S",
:merchant_id=>"BE1...H66",
:created_at=>"2017-10-16T07:05:29Z",
:creator_id=>"BE1...H66", :device=>{
:id=>"DEV...647",
:name=>"iPhone 7 Plus"},
:payment_url=>"https://squareup.com/dashboard/sales/transactions/KXL...tMF",
:receipt_url=>"https://squareup.com/receipt/preview/4867tam...o5S",
:
:inclusive_tax=>[],
:additive_tax=>[],
:tender=>[{
:id=>"4867tampXm52hAvQ9To5S",
:type=>"CASH",
:name=>"Cash",
:receipt_url=>"https://squareup.com/receipt/preview/4867tam...o5S",
:total_money=>{
:amount=>1500,
:currency_code=>"JPY"
},
:
}],
:refunds=>[],
:itemizations=>[{
:name=>"Custom Amount",
:quantity=>1.0,
:itemization_type=>"CUSTOM_AMOUNT",
:item_detail=>{
:category_name=>"",
:sku=>""
},
:
:taxes=>[],
:discounts=>[],
:modifiers=>[]
}]
}
このようにしてWebhookの処理が可能です。取引情報が取り出せれば、自社システムと連携させるのも難しくないでしょう。
なおWebhooksなのでイベントを受け取るサーバはインターネット上に公開されている必要があります。また、外部からのPOSTリクエストを許可するようになっていなければなりませんので注意してください。
今回のRubyのコードはgoofmint/Square_Webhook_Ruby: SquareのWebhook APIをRubyで利用するためのデモコードですにアップロードしてあります。Herokuでも立てられますので、手軽に使えるはずです。