Square의 Webhooks API를 사용해보기

결제된 시점에 시스템에 알리고 싶지 않을까요? 이것을 실현할 수 있는 것이 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에서도 세울 수 있으므로 쉽게 사용할 수 있어야합니다.

Square Connect API Documentation