Webhook

Webhookとは

Webhookとは、ユーザーが自由に定義を行える、HTTPリクエスト形式のコールバックのことです。 マーチャントはCheckoutセッションで直接レスポンスを得る以外に、このWebhookを利用してイベントの通知を受け取ることができます。

Webhookを利用してイベントの通知を受け取るために、マーチャントはエンドポイントとなるURLを指定することになります。 WebhookのエンドポイントとなるURLを登録しておけば、自分のアカウントに関連するイベントが発生した際に通知を受け取ることができます。Webhookを実装しない場合でもPaidy APIの利用は可能ですが、実装することを強くお勧めします。

このWebhookが活躍するのは、以下の場面です。

  • データを同期したい場合: WebhookのエンドポイントとなるURLを登録しておけば、イベントの発生とほぼ同時にそのURLで通知を受け取ることができます。つまり、APIリクエストの結果を受け取る必要があるマーチャント側のサービスが直接そのリクエストを行っていない場合でも、Paidy側のデータと同期することができます。
  • 通信関連の問題が発生した場合: Paidy Checkoutのプロセスでは、注文のAuthorizeの結果をまずはコールバック関数が受け取り、処理を行った後ではじめてマーチャントのバックエンドサーバーにPayment IDが送られます。コンシューマー側の通信環境の問題で万が一このCheckoutプロセスの途中で通信が途切れても、マーチャントはAuthorizeが完了したという通知をWebhookを介して受け取ることができます。
  • 監視:マーチャントは自身のアカウントに関連するイベントの通知をWebhook経由で受け取ることで、特定のイベントを監視することができます。これにより、予め用意しておいたコードを実行して特定のイベントに対処することが可能になります。例えば、Captureリクエストやキャンセルリクエストを実行する際のトリガーとしてWebhookの通知を利用するマーチャントもいます。

Webhookを実装しない場合でもPaidy APIは利用できますが、実装することを強くお勧めします。非常に稀なケースとして、決済のAuthorizeを行う際にコールバック関数が実行されないことがありますが、その場合でもWebhookを実装しておけば適切に対処できます。逆に、Webhookだけを使用するのもお控えください。決済プロセスを進めるにあたり、JavaScriptのコールバック関数とWebhookはどちらも重要です。両方とも実装しておくことが強く推奨されます。

Webhookの流れ

Webhookの流れ

  1. マーチャントがPaidy APIにリクエストを送ると、リクエストの処理結果を示すHTTPレスポンスコードを伴うレスポンスが返ってきます。
  2. その際、マーチャントがWebhookを設定している場合はさらにイベントオブジェクトが生成され、マーチャントが指定したURLにHTTP POSTリクエストの形式で送信されます。 このPOSTリクエストにはイベント関連のデータがJSON形式で含まれています。
  3. 次にマーチャントが200 HTTP Statusコードをレスポンスして、Webhookを受信したことを知らせます。 レスポンスが200以外の場合、またはレスポンスが得られない場合は、エラーが発生したとみなされます。

サポートされているイベントの種類

現在のところ、リクエストが成功した場合に以下のイベントが発生した際にWebHookによる通知が行われるようになっています。

  • イベントの種類

    リクエスト

  • 決済

    決済のAuthorize
    決済のCapture
    決済のRefund
    決済のアップデート
    決済のClose

  • トークン

    トークンの有効化(Activate)
    トークンの一時的な無効化(Suspend)
    トークンの回復(Resume)
    トークンの削除(Delete)

通知の対象となるイベントの種類は今後追加される可能性があるため、こちらにリストアップされているもの以外にも通知を受け取る場合があります。

遅延と再試行

Webhookの通知はイベントが発生した時点で作成され、通常はリアルタイムに近いタイミングで通知を受信することになります。しかし、通知の受信が遅れる場合があります。

遅延が生じる可能性があるという点を念頭に置いてください。発生したイベントの種類(決済のAuthorizeなど)を問わず、どのイベントでも遅延が生じる可能性があります。また、ネットワークの遅延によりWebhookが失敗(タイムアウト)する可能性があり、その場合は再試行が行われます。

この再試行は最大で9回繰り返されます(合計で10回メッセージを送信することになります)。まずは10秒間隔で再試行を3回行い、それ以降は指数関数的に徐々に間隔を広げていき、最終的に10分の間隔を空けて最後の再試行が行われます。処理成功を知らせるレスポンスをAPIが受信しないまま再試行が終了しても、この通知が再び送信されることはありません。

また、再試行中に後から他の決済イベントが発生した場合、そのイベントに関する通知も引き続き処理され、Webhook経由で送信され続けます。

Webhookの導入

わずか3ステップで簡単にWebhookを設定し、動作確認を行えます。

ステップ 1: WebhookのエンドポイントとなるURLをマーチャントダッシュボードで登録します。

ステップ 2: 確実にマーチャント側のエンドポイントでWebhookのメッセージを受信できるよう、これらのIPアドレスがブロックされないようにしてください。 Paidyは以下のIPアドレスからWebhookを送信します: 52.199.50.20 と 52.199.62.26

ステップ 3: マーチャントダッシュボードからテスト用のメッセージを送信し、URLの入力が正しいこと、またそのURLでWebhookによる通知を受け取れることを確認します。

任意の構成

Webhookは非同期的に処理されるため、一定の順序が保証されません。また冪等性が保たれており、同じ種類のイベントに関する通知が複数回送信される可能性があります。そのため、必要に応じて以下のようにシステムを構成してください。

  • WebHookを実装すると自動的にすべてのイベントが通知の対象になります。必要なWebhookのみを処理したい場合は、通知をフィルタリングするようにシステムを構成してください。
  • Webhookは必ず一定の順序で送信されるというわけではありません。例えば、ある決済で発生したAuthorizeイベントの通知を、Captureイベントのものよりも後に受け取る可能性があります。そのため、例えば有限オートマトンなどのロジックを利用してシステムがこれに対処できるようにしておくことが推奨されます。
  • 同じ通知のコピーを複数回受信する可能性があります。そのため、すでに処理を済ませたWebhookを破棄するようにシステムを構成しておくことが推奨されます。

テスト用アカウントにおけるWebhook

決済情報のサンプルが含まれるWebhookがテスト用のURLに送信されます。 ただしマーチャントがこの設定を行っていない場合、このテストでWebhookは送信されません。

Webhookの利用方法

Webhookによる通知の受信

Webhookのエンドポイントとしてマーチャントが登録してあるURLに対して、リクエスト関連のイベントが発生する度にデータがPOST送信されます。このリクエストにはイベントに関するデータがJSON形式で含まれています。 また、発生した決済イベントの種類と結果は両方ともリクエスト内のstatusフィールドで分かるようになっています。

Webhookによる決済関連の通知

  • パラメーター

    説明

  • payment_id

    Paidy決済(ペイメント)ID。

  • capture_id

    Paidy回収(キャプチャー)ID (CaptureイベントおよびRefundイベントの場合のみ)。

  • event_type

    Webhookは決済関連のイベントが発生した場合にのみ送信されます。初期値は「payment」。 (発生した決済イベントの種類はstatusフィールドでご確認ください。)

  • status

    発生した決済イベントの種類と結果を示すフィールドで、 以下のような値が入ります。
    authorize_success
    capture_success
    refund_success
    update_success
    close _success

  • order_ref

    マーチャントが割り当てる注文IDまたはカートID。

  • reason

    払い戻しの理由 (Refundイベントの場合のみ)。

  • timestamp

    イベントが生成された日時(ISO 8601のフォーマットに準じるUTC)。

例えば、Captureリクエストが成功した際は次のようなWebhookの通知を受信します。


  {
  "payment_id":"pay_WFDYLhEAAEQA42Dw",
  "capture_id":"cap_WFIk5yIAACIAC6n3",
  "status":"capture_success",
  "event_type": "payment",
  "order_ref": "20161214ato06",
  "timestamp":"2016-11-15T05:06:47.189Z"
}

現在のところ、レスポンスにはevent_datetimeフィールドとtimestampフィールドの両方が含まれていますが、timestampの方を使用するようにしてください。event_datetimeフィールドは廃止される予定になっています。

Webhookによるトークン関連の通知

  • パラメーター

    説明

  • token_id

    「tok_」で始まるPaidyのトークンID。

  • status

    発生したイベントの種類と結果を示すフィールドで、以下のような値が入ります。
    activate_success
    suspend_success
    resume_success
    delete_success

  • timestamp

    イベントが生成された日時(ISO 8601のフォーマットに準じるUTC)。

イベントが生成された日時(ISO 8601のフォーマットに準じるUTC)。 例えば、回復イベントが成功した際は次のようなWebhookの通知を受信します


  {
    "token_id":"tok_WK5KjCEAAA0RvPp9",
    "event":"resume_success",
    "timestamp":"2016-11-15T05:06:47.189Z"
  }  

Webhookによる通知へのレスポンス

マーチャント側のエンドポイントがWebhookを受信したら、200 HTTP Statusコードをレスポンスする必要があります。レスポンスが200 HTTP Statusコード以外だった場合、または10秒以内にレスポンスが得られなかった場合、Paidyは継続してリクエストを送信し続けます。

ベストプラクティス

決済データの検証

Authorizeが成功すれば、Webhook経由でこの新しいAuthorizeに関する通知を受信します。その際、可能な限りPaidy APIにリクエストを送信して決済データの有効性を検証し、確認が取れてからこのPayment IDを保存するようにバックエンドシステムを構成してください。

推奨フロー

  • バックエンドシステムから/payments/{id}エンドポイント({id}の部分はPayment ID)にGETリクエストを送信します。このリクエストの処理が成功すると決済オブジェクト全体が返ってきます。
  • amountとorderの値が正しいことを確認します。この値が正しい場合は決済データが有効ですので、安心して決済オブジェクトをデータベースに保存できます。
  • statusがAUTHORIZEDになっていれば、準備ができ次第、いつでもCaptureを実行することができる状態です。

Webhookの動作確認

Webhookの設定に関して間違えやすいのは以下の2点です。

  • マーチャントダッシュボードで誤ったURLを入力している
  • Webhookによる通知を受信した際に200ステータスコードをレスポンスし忘れている

システムの動作確認を行い、上記の設定を正しく行っているかどうかご確認ください。