Webhooks

DEUNAのWebhookは、2つの異なるサーバー間フローをカバーします：バックエンドに支払いステータスの変更を公開する通知と、チェックアウト中にDEUNAがマーチャント固有のデータやロジックを要求できる同期コールバックです。統合で達成する必要があることに応じてフローを選択してください。

ブラウザリダイレクト、SDKコールバック、およびプロバイダーからDEUNAへのコールバックは、別の統合インターフェースです。これらを支払いの証明や、これらのバックエンドフローの代替として使用しないでください。

注文および支払いステータス通知これについて Athia に質問#

ステータス通知は、正規化された支払いステータスが加盟店が購読したイベントと一致した場合、最新の注文スナップショットをバックエンドに配信します。これらの通知は非同期です：支払いライフサイクルは、ビジネスロジックの完了を待機しません。

ステータス配信の設定

各環境の配信契約を定義します：

利用可能なイベントは、以下のドキュメントに記載されている支払いライフサイクルに従います： 支払いワークフローとステータス。イベントの網羅性は支払い方法によって異なる場合があります。すべての支払い方法がすべての支払い操作やステータスをサポートしているわけではないためです。

デフォルトペイロード

カスタムペイロード変換がない場合、DEUNAはHTTP POST ～ Content-Type: application/json を送信し、現在の注文を order プロパティの下に含めます：

{
  "order": {
    "token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "transaction_id": "transaction-456",
    "status": "succeeded",
    "payment_status": "processed",
    "currency": "USD",
    "total_amount": 5000,
    "payment": {
      "data": {
        "status": "processed",
        "processor": "example_processor",
        "external_transaction_id": "processor-789"
      }
    }
  }
}

注文には、その取引に関連する顧客、商品、金額、支払い、プロセッサー、不正検知、メタデータ、およびカスタムフィールドのデータが含まれる場合があります。 order.payment.data.status を権威ある支払い状態として扱い、 order.token, order.order_idおよび該当する取引識別子を調整に使用してください。

マーチャント固有の設定では、HTTPメソッド、ヘッダー、URLパラメータ、購読するステータス、およびペイロードの形状を変更できます。カスタム設定が有効な場合は、デフォルトのボディを想定するのではなく、そのマーチャント向けに認定された正確な契約を実装してください。

署名を検証する

現在の配信では X-Signature ヘッダーが追加されます。これは以前の例で言及されていた X-Deuna-Signature.

1. フレームワークが解析または再シリアライズする前に、未変更のリクエストボディを読み取ります。
2. 配信フローと環境で認定されたHMAC-SHA256およびBase64検証手順を適用します。
3. 計算された値を X-Signature 定数時間比較を使用します。
4. 値が一致しない場合、処理前にリクエストを拒否します。

ペイロード変換が有効な場合、ステータス通知と動的Webhookは常に同じ入力を署名するとは限りません。署名された入力と鍵導出が認証中に確認されるまで、これらのフロー間で検証器を再利用しないでください。

プライベートAPIキーはサーバー上に保持してください。ブラウザコード、モバイルアプリケーション、ログ、またはWebhookレスポンスに配置しないでください。

受信を確認し、調整します

1. ペイロードを信頼する前に署名を検証してください。
2. 注文トークンとイベントまたは結果の支払いステータスを含む重複排除キーを記録してください。
3. リクエストが確実に受け入れられたらすぐに 2xx 成功レスポンスを返してください。
4. 履行、キャンセル、キャプチャ、返金、またはその他の不可逆的なアクションの前に、信頼できる注文状態を再読み取りまたは調整してください。
5. ローカルの記録を新しい状態から古い状態に戻すような通知は無視してください。

配信失敗は再試行できます。配信が必ず1回だけ、再試行間隔が固定、またはライフサイクル順に到着するとは想定しないでください。

ダイナミックチェックアウト Webhookこれについて Athia に質問#

動的Webhookは、同期型のマーチャント固有のコールバックです。チェックアウトが設定されたイベントをトリガーすると、DEUNAは署名付きリクエストをエンドポイントに送信し、レスポンスを検証し、許可された更新のみを適用し、設定された結果をチェックアウトに返します。

動的Webhookはマーチャント実装の一部として有効化・設定されます。ブラウザやモバイルコードから登録されるものではありません。

設定と実行フロー

マーチャント設定の一環としてDEUNAでWebhookを設定します。イベント名、宛先、リクエストとレスポンスの形式、検証ルール、コールバックが更新可能なフィールドについて合意します。設定後、チェックアウトは同じ合意された契約を通じてイベントを実行できます。

マーチャントと環境に対してイベントが設定されていない場合、DEUNAはエンドポイントを呼び出しません。実行されなかった必須コールバックは、認証中の設定問題として扱ってください。

設定機能

以下の抜粋は、チップ計算定義の核心を示しています。これは設定データであり、ブラウザから送信すべきリクエストではありません：

{
  "event_name": "tip_amount_updated",
  "url": "https://merchant.example.com/checkout/tips",
  "http_method": "POST",
  "fields_update": {
    "fields": ["TotalAmount"],
    "custom_fields": ["tipAmount"]
  },
  "response_body": {
    "fields": ["Order"],
    "custom_fields": ["tipAmount"]
  },
  "response_template": "{\"order\":{\"total_amount\":{{ .result.total_amount }},\"custom_fields\":{\"tipAmount\":{{ .result.tip_amount }}}}}",
  "response_data": "{\"result\":{\"total_amount\":5500,\"tip_amount\":500}}"
}

実行中、チェックアウトはイベント固有の入力を提供できます：

{
  "data": {
    "tip_amount": 500
  }
}

ペイロードテンプレートがない場合、マーチャントエンドポイントはそのイベントデータを受け取ります。ペイロードテンプレートがある場合、テンプレートは現在の注文とイベント入力の両方を使用して送信JSONを構築できます。

マーチャントエンドポイントを実装する

動的呼び出しには以下が含まれます X-Signature および X-Deuna-Operation。ペイロードテンプレートが送信本文を変更する場合、認定中に合意された署名検証入力を使用すること。上記のステータス通知契約と同一であると想定しないでください。

応答伝播が無効な場合、デフォルトのマーチャント応答には以下を含めることができます order, shipping_rate, および shipping_methods。DEUNAは設定で選択された応答フィールドのみを返します。応答伝播が有効な場合、マーチャント応答は有効なJSONである必要があり、動的結果として直接返されます。

実用的なパターン

チップ計算の例

この例は、設定されたチップイベントに対するチェックアウトからマーチャントへの完全なパスを示しています。

チップ定義の場合、マーチャント応答で変更が予想される金額とカスタムフィールドのみを許可リストに登録します。マーチャントエンドポイントは一貫した注文合計の計算を担当します。

サンドボックスでテストこれについて Athia に質問#

ステータス通知をテストする

動的Webhookをテストする

関連ドキュメントこれについて Athia に質問#