pending から authorised、または authorised から waiting へ移ったときに)サーバーがリアルタイムで通知を受け取れます。API をポーリングする代わりにエンドポイントを登録すれば、ステータスが変わるたびに Hello Clever が自動的に POST リクエストを送信します。
Webhook の仕組み
決済のステータスが変わると、Hello Clever は設定されたendpoint_url に対して、取引の現在の状態を示す JSON のペイロードとともに POST リクエストを送信します。受信を確認するため、エンドポイントは HTTP 200 を返す必要があります。返さない場合、Hello Clever は各試行の間に 15 分の間隔を置いて最大3回リトライします。
リトライによって同じペイロードが複数回配信される可能性があるため、Webhook のエンドポイントでは冪等な処理を実装してください。イベントの重複排除には
uuid の項目を使ってください。Webhook の設定
Webhook のエンドポイントは2つの方法で設定できます。 SDK 連携:既定の Webhook の URL を登録するには Hello Clever へご連絡ください。SDK 経由で作成されたすべての決済がその URL へ通知を送信します。 API 連携:決済作成のリクエストにwebhook_notification のオブジェクトを含めます。指定した場合、その決済については既定の Webhook の URL を上書きします。
object
決済作成のリクエストに含める Webhook の設定です。
決済のステータス
Hello Clever は、決済が次のいずれかのステータスに移るたびに Webhook の通知を送信します。決済が
in_dispute のステータスにある場合、異議解決の手続きに証拠を提出するため、Hello Clever のサポートへご連絡ください。Webhook のオブジェクト
各 Webhook の POST のボディには次の項目が含まれます。ペイロードの例
オーソリ済みカードのトークン
カード決済がauthorised または waiting のステータスに達すると、Hello Clever は Webhook のペイロードに token のオブジェクトを含めます。このトークンは安全に保管してください。同じ顧客に対して、カード情報の再入力を求めずに将来の決済を作成できます。
Webhook のセキュリティ
Hello Clever は2つのセキュリティの仕組みに対応しており、単独でも併用でも利用できます。Authorization ヘッダー
Webhook の設定でauthorization_header を指定すると、Hello Clever はエンドポイントへのすべての Webhook リクエストの Authorization ヘッダーでその値を送信します。
HTTP Webhook 署名 (HMAC-SHA256)
Hello Clever は各 Webhook のペイロードを HMAC-SHA256 で署名し、その署名をHTTP-WEBHOOK-SIGNATURE のヘッダーで送信します。
1
Webhook Secret Key を確認する
Merchant Portal で Dashboard → Developer → Authentication → Webhook タブへ移動し、Webhook secret key の欄の値をコピーします。
2
想定される署名を計算する
生のリクエストボディ(JSON をパースして再度文字列化しないこと)と Webhook Secret Key を使います。
3
比較して受け入れるか拒否する
署名が一致すれば、ペイロードは正当で改変されていません。異なる場合はリクエストを拒否してください。改ざんされている、または信頼できない送信元から送られた可能性があります。
エラー処理とリトライ
エンドポイントが HTTP200 を返さない場合、Hello Clever は各試行の間に 15 分の間隔を置いて、Webhook の呼び出しを最大 3 回リトライします。
リトライを正しく扱うには次のようにしてください。
- 重い処理を行う前に、Webhook を受け取った時点で直ちに
200を返してください。 - タイムアウトを避けるため、イベントは非同期に処理してください(キューを使うなど)。
- 重複した配信を検出して破棄するため、
uuidの項目を使ってください。
エラーコード
決済が失敗すると、pay_code のオブジェクトに error_code と error_message が含まれます。次の表はすべてのエラーコードの一覧です。
ベストプラクティス
- 処理を行う前に、すべての受信リクエストで
AuthorizationヘッダーまたはHTTP-WEBHOOK-SIGNATUREを検証してください。 - リトライによる副作用の重複を防ぐため、
uuidの項目を使って冪等性を実装してください。 - リクエストを受け取ったら直ちに
200 OKを返し、ペイロードは非同期に処理してください。 - Webhook のエンドポイントの URL は非公開に保ち、公開の場での共有は避けてください。
- 通信中のペイロードを保護するため、Webhook のエンドポイントには HTTPS を使ってください。
- 開発中は webhook.site や ngrok のようなローカルトンネルを使ってエンドポイントをテストしてください。