Webhooks

DEUNAは、設定された支払いまたは注文の状態が変更されたときに、バックエンドに更新された注文の概要を送信するために、ウェブフックを使用します。 デフォルトの商社向けボディには、注文そのものが含まれています。 これはStripeのようなイベントエンベロープではありません。

仕組み#

宛先を設定#

Purchase V2の場合、以下の「非同期注文通知」フィールドにHTTPS受信URLを指定してください。

{
  "order": {
    "order_id": "merchant-order-123",
    "webhook_urls": {
      "notify_order": "https://merchant.example.com/webhooks/deuna/orders"
    }
  }
}

DEUNA は注文単位の URL を保存し、オンボーディング時に設定された加盟店設定から不足している値を補完できます。現在の署名付き通知フローでは、加盟店単位の送信先とステータス購読設定を使用します。各環境で有効な URL を TAM に確認してください。1 件の注文に対して非同期 Webhook URL と同期 Webhook URL を同時に指定することはできません。

注文ステータス通知では、汎用的な Webhook エンドポイント登録リソースを使用しません。上記の注文フィールドを設定するか、DEUNA の Technical Account Manager（TAM）と合意した加盟店単位の設定を使用してください。動的チェックアウトコールバックでは、以下で説明する別の API を使用します。

サポートされているデリバリーフロー#

非同期配送を使用してください。ただし、DEUNAが別のモードを明示的に有効化および認証している場合を除く。

DEUNA は、対応する注文または支払いステータスの値が変更された場合、選択された決済プロセッサが変更された場合、および対応する不正検知または 3DS の判定が行われた場合に通知候補を作成します。設定された購読によって、配信される支払いステータスが決まります。すべてのステータス遷移で Webhook が生成されるわけではありません。

このメカニズムは、サポートされている非同期決済、返金、およびキャンセル操作の最終結果と、それに関連する更新情報を処理します。 支払いワークフローとステータス 公開ステータス 非同期決済、払い戻し、およびキャンセル これらの操作フローについて。

ダイナミックチェックアウト Webhook#

動的チェックアウト Webhook は、独立した同期フローです。チェックアウトアクションからイベント名を指定して加盟店のエンドポイントを呼び出し、レスポンスを検証または変換し、トークン化された注文の指定フィールドを更新して、選択した値または加盟店のレスポンスを呼び出し元に返すことができます。

このフローは、チップ、ロイヤリティポイント、寄付、およびカスタムクーポンなどの、商社固有のチェックアウトアクションに使用します。 非同期の支払いステータス配信の代替として使用しないでください。

効果的な API Gateway は、これらのダイナミック Webhook 機能を公開します。

実行リクエストは、イベント固有の入力を渡すことができます。 data:

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

DEUNA は加盟店とイベント名に対応する有効な設定を読み込み、設定された加盟店 URL を呼び出します。設定では、HTTP メソッド、ヘッダー、URL パラメータ、クエリパラメータ、ペイロードとレスポンスのテンプレート、検証、更新する注文フィールド、返すレスポンスフィールド、および加盟店のレスポンスを伝播するかどうかを選択できます。

アウトバウンドの商社リクエストには、以下のものが含まれます。 X-Signature および X-Deuna-Operation。処理は同期的に行われます。加盟店側のタイムアウト、無効なレスポンス、検証エラー、失敗した HTTP レスポンスは呼び出し元に返されます。加盟店にイベント名の設定がない場合、DEUNA は加盟店のエンドポイントを呼び出さずに空の成功レスポンスを返します。

動的 Webhook 設定は加盟店固有で、注文を変更できます。有効化する前に、イベント名、認証、許可されるフィールド、テンプレート、検証、タイムアウト、伝播されるレスポンスを TAM に確認してください。詳しくは、 エンドポイント: カタログ を参照して、ゲートウェイの在庫を確認してください。

デフォルトの注文ステータスペイロード#

デフォルトのリクエストは HTTP です。 POST ～ Content-Type: application/json および、以下のような構造:

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

完全な注文オブジェクトには、注文レスポンスで返されるものと同じ注文、顧客、商品、金額、支払い、決済プロセッサ、不正検知、メタデータの各フィールドを含めることができます。

• 決済の状態： order.payment.data.status
• 安定したビジネス識別子： order.token, order.order_idおよび、関連するトランザクション識別子

カスタム商取引設定により、このボディを変換できます。受信側が上記のデフォルトの形状を使用していない場合は、TAM（テクニカルアカウントマネージャー）に正確なペイロードを確認してください。

注文ステータスの配信認証#

現在の署名済み決済フローでは、以下のリクエストヘッダーが送信されます:

X-Signature: <signature>

署名は、JSONペイロードと商人の認証情報から、HMAC-SHA256とBase64エンコーディングを使用して生成されます。

ペイロードを検証する前に、オンボーディング時に提供された認証情報と検証手順を使用して、正確なリクエストボディを確認してください。代替ヘッダー名や、ドキュメントされていないSDKヘルパーに依存しないでください。

承認と処理#

リクエストが検証され、永続的にキューに入れられた時点で、HTTPステータス200または別の2xxレスポンスを返してください。空のボディを返すことも可能です。JSONを返す場合は、DEUNAが受け入れるレスポンス形式は以下のとおりです。

{
  "status": "success",
  "data": {
    "order_id": "merchant-order-123"
  }
}

異なる、空でない注文IDをこのレスポンスで返すのは、DEUNAが商人の注文IDを置き換える場合にのみ行ってください。

ネットワークエラー、タイムアウト、および失敗した応答により、別の配送試行が発生する可能性があります。固定の再試行間隔に依存せず、配送順序を想定しないでください。処理を冪等にし、各スナップショットを最新の既知の支払い状態と比較してください。

サンドボックスでテスト#

1. HTTPS 経由でリクエストヘッダーと元のボディを記録する受信機能を公開します。
2. サンドボックスのPurchase V2リクエストで、非同期の注文通知URLを設定してください。ただし、商人のレベルでURLがすでに設定されている場合は、設定しないでください。
3. 支払い、またはステータスを変更する非同期のキャプチャ、払い戻し、またはキャンセルを完了します。
4. ペイロードの形式、設定されたステータス範囲、署名ヘッダーの動作、確認、および重複処理について確認してください。

注文ステータスフローは、一般的な /webhook_endpoints API またはローカルフォワーディング CLI コマンドを提供しません。 実際のサンドボックス状態の変更を生成してテストしてください。 ダイナミックチェックアウト Webhook は、検証された設定と実行ルートを通じてテストしてください。