メインコンテンツへスキップ
このページで

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

フロー実行タイミング用途
注文および支払いステータス通知購読している支払いステータスが変更された後継続的なポーリングなしに、フルフィルメント、調整、顧客注文ステータスを更新します。
動的チェックアウトWebhookチェックアウトがマーチャントの応答を待機している間クーポンやカードに応じた割引の適用、チップや税額の計算、配送情報の取得、データの検証を行います。

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

注文および支払いステータス通知#

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

01 · state
支払いステータスの変更
DEUNAは、processed、authorized、captured、denied、voided、refundedなどの正規化された支払い結果を記録します。
02 · subscription
イベントが選択されます
支払いステータスは、以下の名前のイベントになります 支払い状況、DEUNAは加盟店のサブスクリプションを確認します。
03 · delivery
注文スナップショットが送信されます
DEUNAは設定済みのリクエストを加盟店の宛先に送信します。
04 · receiver
バックエンドで調整を行います
サーバーは署名を検証し、リクエストを確認し、更新を冪等に処理します。

ステータス配信の設定

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

設定定義する内容
宛先ステータス通知を受け付けるHTTPSエンドポイント。
イベント次の payment.<status> 注文ライフサイクルで必要なイベント。
リクエスト契約静的なヘッダー、URLパラメータ、および承認済みのペイロード変換。
失敗時の処理統合で合意した、受信確認、再試行、監視、および調整の動作。

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

デフォルトペイロード

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

注文ステータス通知JSON
{
  "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#

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

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

設定と実行フロー

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

シーケンス図
1Merchant team andbackend2DEUNA3Checkout UIConfigure event, endpoint,contract, and allowedupdatesTrigger the configured eventwith order and inputSend the signed requestReturn the agreed JSONresponseValidate the responseand apply permittedupdatesContinue with the configuredresult
商社または顧客DEUNA

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

設定機能

構成要件制御内容
event_name必須加盟店固有のイベント名です。英字、数字、ハイフン、アンダースコアを使用します。トリガーは別途設定してください。
url必須加盟店エンドポイントの送信先です。連携にはHTTPSを使用してください。
http_method任意HTTPメソッド: GET, POST, PUT、または PATCH。デフォルトは POST.
headers任意配列の要素は key および value のペアです。追加のリクエストヘッダーに使用します。値には注文テンプレートを使用できます。
params, query_params任意各配列の要素は key および value のペアです。URLのプレースホルダーとクエリパラメーターに使用します。値には注文テンプレートを使用できます。
payload_template任意現在の注文とイベントの入力から加盟店向けJSONリクエストを作成します。省略すると、リクエスト本文にはイベントの入力のみが含まれます。
response_template任意加盟店のJSONを注文レスポンスの契約にマッピングします。エンドポイントがその契約どおりに返す場合は省略します。
response_data次を使用する場合に必須: response_template設定時にレスポンステンプレートを検証するための、文字列としてエンコードしたJSONです。実行時の加盟店レスポンスではありません。
error_response_template任意加盟店の別形式のエラーをマッピングします。省略した場合、加盟店のエラーレスポンスで使用するフィールドは code および message.
fields_update.fields任意注文で更新を許可するフィールドの配列です。コールバックで置き換える金額、割引リスト、商品フィールドをすべて含めます。以下の価格フィールドを参照してください。
fields_update.custom_fields任意変更を許可するカスタムフィールド名の配列です。フィールドを宣言しておく必要があり、返す値は注文のカスタムフィールドスキーマに適合する必要があります。
response_body.fields設定の作成時に必須指定できる値は Order, ShippingRate、および ShippingMethodsです。マッピング後のレスポンスには注文が含まれ、このリストでは追加の配送結果も選択します。注文内に含まれるプロパティを制限するものではありません。
response_body.custom_fields任意チェックアウトの結果に含める、宣言済みカスタムフィールド名の配列です。これらのフィールドの更新権限とは別の設定です。
propagate_response任意デフォルト false。注文の更新では値を false にしてください。もう一方のモードでは、加盟店のJSONが次のフィールドに含まれます: dynamic_response 。このモードではマッピング後の注文結果は返しません。

価格の更新を設定する

設定フィールド名とレスポンスのJSONパスは異なります。プロモーションに必要な更新のみを選択してください。

設定値: fields_update.fields加盟店レスポンスのデータ更新内容
TotalAmountorder.total_amount支払総額を置き換えます。
TotalDiscountorder.total_discount割引合計額を置き換えます。
Discountsorder.discounts注文レベルの割引配列全体を置き換えます。
Items.TotalAmountorder.items[].id, order.items[].total_amountIDで既存の商品を照合し、金額、元の金額、割引合計を更新します。
Items.Discountsorder.items[].id, order.items[].discountsIDで既存の商品を照合し、割引参照を置き換えます。
Shippingorder.shipping配送の元の金額、割引合計、割引参照を置き換えます。

Webhookは各値を個別に設定します。割引リストから支払総額、割引合計、商品ごとの配分を再計算しません。成功時は毎回、更新を許可したすべてのフィールドを返してください。選択したフィールドを省略すると、金額がゼロになったりリストが空になったりすることがあります。省略は部分更新の指定にはなりません。

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

動的Webhook設定抜粋JSON
{
  "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}}"
}

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

イベント入力JSON
{
  "data": {
    "tip_amount": 500
  }
}

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

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

懸念事項マーチャントエンドポイント要件
繰り返し実行同じ入力の繰り返しを冪等に処理してください。プロモーションの入力が変わった場合は再計算します。
応答契約設定された応答形式または応答テンプレートに一致するJSONを返すこと。
必須フィールド割引を削除する際のゼロ値も含め、設定された更新フィールドをすべて返してください。
レイテンシー統合で認定されたタイムアウト内に完了すること。チェックアウトは応答を待機します。
エラービジネスまたは処理の失敗に対しては、設定されたエラー形式を使用して非-2xx 応答を返すこと。

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

レスポンス転送が無効な場合、加盟店レスポンスに含められるフィールドは order, shipping_rate、および shipping_methodsです。DEUNAはマッピング後の注文と設定済みの追加結果を返します。転送が有効な場合、加盟店レスポンスは有効なJSONである必要があり、次のフィールドで公開されます: dynamic_response。注文価格の再計算にはマッピングを行うフローを使用してください。

実用的なパターン

カードに応じた割引

チェックアウト中に入力されたカードに応じてプロモーションを適用するには、動的チェックアウトWebhookを使用します。加盟店のバックエンドが適用条件を判定して割引額を計算し、DEUNAが支払い前に設定された注文の更新を適用します。

対象となる銀行識別番号(BIN)、カードブランド、割引ルールは加盟店のバックエンドで管理します。DEUNA Technical Account Manager(TAM)に対象リストを共有する必要はありません。DEUNAは設定されたトリガーの実行時にエンドポイントを呼び出します。加盟店のエンドポイントはすべてのリクエストを評価し、割引を適用した注文、またはそのプロモーションを適用しない注文を返します。

支払い前に実行するよう設定されたコールバックは、その設定済みフローを通る各支払いリクエストの前に実行されます。DEUNA側でBINの適用条件による絞り込みは行いません。BIN検出コールバックは、顧客がカードを入力または変更した際に、より早い段階でチェックアウトの価格を更新するために実行できます。コールバックの実行タイミングとリクエストデータをDEUNAと確認してください。

チェックアウトが支払いリクエストを作成する前に、価格の再計算と注文の再取得を完了してください。支払い前のコールバックで保存済みの注文合計を更新しても、その支払いリクエストにすでに設定された金額は自動的に再構築されません。

以下の例ではBIN検出を使用します。カード入力では、顧客がカード情報をすべて入力する前に、先頭6桁の入力後にBINイベントが発生することがあります。BINの検出は、カード番号全体の有効性や支払いの承認を確認するものではありません。

シーケンス図
1チェックアウト2DEUNA3加盟店のバックエンドカードのBINを検出または変更設定済みの割引イベントを実行注文とカード入力を含む署名付きリクエスト適用条件を判定して合計を計算対象カード割引適用後の合計と割引リスト対象外のカードこのプロモーションを除いた合計と割引許可された注文の更新を保存更新後の注文と合計価格を表示して支払いリクエストを作成更新後の合計で支払いを送信
商社または顧客DEUNA

環境ごとにこのフローを設定し、実装してください。

  1. DEUNAとWebhookを設定します。 HTTPS送信先と、想定するリクエストおよびレスポンスをDEUNA Technical Account Manager(TAM)に伝えてください。イベント名、コールバックの実行タイミング、署名の検証方法、タイムアウト、エラー処理、レスポンスで更新できる注文フィールドを取り決めます。プロモーションの適用条件の判定と割引額の計算は、加盟店のバックエンドで管理してください。
  2. 取り決めたトリガーを接続します。 支払い前のコールバックの場合は、対象の支払いフローでの実行をDEUNAと設定してください。以下のBIN検出の例では、BINの検出や変更時に取り決めたイベントが実行されるよう、チェックアウトの連携を調整します。Webhookを登録するだけでは、カード入力との接続は行われません。Web SDKのPayment WidgetとElementsでは、 onCardBinDetected が提供する値は cardBin および cardBrandです。詳細は Web SDKのコールバックリファレンスを参照してください。クライアントのコールバックとサーバー間のWebhookは別々のステップです。
  3. 加盟店のエンドポイントを実装します。 署名付きリクエストを検証し、取り決めた注文情報とBINを使ってサーバーでプロモーションの適用可否を判定してください。秘密の認証情報はサーバーに保持し、このフローではカード番号全体やセキュリティコードを要求しないでください。呼び出しが繰り返されても、同じ割引を重複して適用しないように処理します。
  4. 再計算した注文を返します。 取り決めたJSONレスポンスで、更新後の支払総額、割引合計、割引配列全体を返してください。以下に示す3つのフィールドの更新を許可し、マッピング後の注文をチェックアウトに返すよう設定します。エンドポイントが別の形式を使用する場合は、レスポンステンプレートを取り決めてください。この更新ではレスポンス転送を無効にします。
  5. 支払い前に価格を更新します。 DEUNAから返された注文を表示し、更新後の総額を支払いに使用してください。顧客がカードを変更したり入力を消去したりした場合に、チェックアウトでプロモーションを削除または再計算する方法を取り決めます。コールバックに失敗した場合に、再試行するか、支払いを停止するか、プロモーションなしで続行するかを定義してください。

たとえば、その他の料金がないUSD 100.00の注文に10%のプロモーションを適用すると、割引額はUSD 10.00、支払総額はUSD 90.00になります。エンドポイントは整合性のある総額を計算する必要があります。適用可否のフラグだけを返しても、注文金額は変更されません。

リクエストとレスポンスの契約例

以下は、その他の割引や料金がない注文の例です。イベント名と送信リクエストの形式は、加盟店との取り決めの一例であり、組み込みのカード割引イベントや全加盟店共通のデフォルトスキーマではありません。使用する前に、TAMと契約内容およびチェックアウトの連携を確認してください。

金額は注文通貨の最小単位の整数で指定します。 10000 はUSD 100.00を表します。先頭のゼロを保持するため、BINは文字列として扱ってください。

チェックアウトは、取り決めたイベントの実行時に次の入力データを渡します。

イベント例card_discountのチェックアウト入力JSON
{
  "data": {
    "cardBin": "411111",
    "cardBrand": "visa"
  }
}

DEUNAと次のマッピングを設定してください。これは設定の抜粋であり、ブラウザから送るリクエストではありません。ペイロードテンプレートは現在の注文とイベント入力を組み合わせます。このテンプレートがない場合、加盟店が受信するのはイベントデータのみです。

カード割引Webhookの設定例JSON
{
  "event_name": "card_discount",
  "url": "https://merchant.example.com/checkout/card-discounts",
  "http_method": "POST",
  "payload_template": "{\"order_token\":\"{{ .Order.Token }}\",\"order_id\":\"{{ .Order.OrderID }}\",\"currency\":\"{{ .Order.Currency }}\",\"total_amount\":{{ .Order.TotalAmount }},\"cardBin\":\"{{ .Payload.cardBin }}\",\"cardBrand\":\"{{ .Payload.cardBrand }}\"}",
  "fields_update": {
    "fields": ["TotalAmount", "TotalDiscount", "Discounts"]
  },
  "response_body": {
    "fields": ["Order"]
  },
  "propagate_response": false
}

加盟店のエンドポイントは、次のcURLと同等のリクエストを受信します。署名と操作のヘッダー値はDEUNAが設定します。 変換後のペイロードの署名検証方法 をTAMと確認してください。

curl --request POST 'https://merchant.example.com/checkout/card-discounts' \
  --header 'Content-Type: application/json' \
  --header 'X-Signature: SIGNATURE_FROM_DEUNA' \
  --header 'X-Deuna-Operation: OPERATION_FROM_DEUNA' \
  --data '{
    "order_token": "21ac49c0-d587-4f25-ae1c-0d60e540c1e8",
    "order_id": "merchant-order-123",
    "currency": "USD",
    "total_amount": 10000,
    "cardBin": "411111",
    "cardBrand": "visa"
  }'

注文フィールドは価格を再計算する注文を識別し、カードフィールドにはイベント入力が含まれます。サーバーで入力を検証し、信頼できる価格およびプロモーションのルールを適用してください。受信した総額には以前の呼び出しによる割引が含まれている可能性があるため、注文のプロモーション適用前の基準額から再計算します。不明なブランドや、カード入力の消去時に空になるBINの処理方法を取り決めてください。

対象となるカードの場合は、成功を示すHTTPステータスとJSON本文を含む次のレスポンスを返してください。

加盟店のレスポンス:対象カードHTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order": {
    "total_amount": 9000,
    "total_discount": 1000,
    "discounts": [
      {
        "amount": 1000,
        "code": "CARD_PROMO",
        "reference": "merchant-promotion-123",
        "description": "Card promotion",
        "type": "order_value",
        "discount_category": "promotion"
      }
    ]
  }
}
レスポンスフィールドJSONの型この例で必須意味
order.total_amountintegerはい割引後の最終支払総額。通貨の最小単位で指定します。
order.total_discountintegerはいカードプロモーションを含む割引総額。同じ通貨の最小単位で指定します。
order.discountsarray (オブジェクトの配列)はい注文に保存する割引の完全なリストです。空の配列を返すと、このリストが消去されます。

プロモーションを解除する場合も含め、成功時は毎回、設定した3つのフィールドをすべて返してください。この例でカードが対象外の場合は、次のように返します。

加盟店のレスポンス:カード割引なしHTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order": {
    "total_amount": 10000,
    "total_discount": 0,
    "discounts": []
  }
}

DEUNAは、 fields_update で許可されたフィールドのみを更新し、保存された注文を order に入れてチェックアウトに返します。上記の加盟店レスポンスには3つの更新フィールドが含まれます。チェックアウトへのレスポンスには、残りのフィールドを保持した注文が含まれます。他のプロモーションが適用されている場合は、返す割引リストに残し、合計を再計算してください。割引が一切残らない場合にのみ、空のリストと割引合計ゼロを返します。

割引オブジェクトの契約

注文の割引配列の各要素は、適用済みの割引を表します。金額には通貨の最小単位の整数を使用します。パーセント割引でも、計算済みの金額を返す必要があります。マッピングされた割引の契約は、以下のフィールドに対応しています。

割引フィールドJSONの型意味
amountintegerこの割引で適用する金額です。
code, referencestring加盟店のプロモーションコードと参照識別子です。
description, details_urlstringプロモーションの説明と、任意の詳細リンクです。
typestring割引の種類: order_value, product、または free_shipping.
discount_categorystring加盟店が定義する割引の分類です。
target_typestring適用先の構成要素(該当する場合): item または shipping.
free_shippingobject配送プロモーションの詳細: is_free_shipping は真偽値、 maximum_cost_allowed は通貨の最小単位の整数です。

これらのフィールドは加盟店のプロモーションロジックの結果を表します。対象BINの設定や、DEUNAによる割引計算を行うものではありません。取り決めた契約で必要なフィールドを含めてください。商品と配送の割引リストでは、次のフィールドを持つ参照オブジェクトを使用します: amount および ref_idx。注文レベルの割引オブジェクト全体を繰り返す形式ではありません。これらの参照と、返す注文の割引との整合性を保ってください。

計算または処理に失敗した場合は、2xx以外のHTTPステータスを返してください。カスタムのエラーマッピングがない場合は、以下のエラー本文を使用します。ステータスは一時的な障害の例であり、エラーコードは加盟店が定義するものです。

加盟店のエラーレスポンスHTTP
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "code": "PROMOTION_UNAVAILABLE",
  "message": "Unable to calculate the card promotion."
}

エンドポイントのエラー形式が異なる場合は、 error_response_template を取り決めてください。対象外のカードは通常の割引なしの結果であり、処理エラーではありません。割引が適用されたと想定せず、チェックアウトは手順5で取り決めた失敗時の動作に従う必要があります。

チップ計算の例

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

シーケンス図
1Shopper + checkoutUI2DEUNA3加盟店のバックエンドtip_amount_updated + ordertokenSigned request with order +tip inputRecalculated total + tipfieldValidate response andapply permittedupdatesUpdated order + tip resultDisplay the new total
商社または顧客DEUNA

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

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

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

動的Webhookをテストする

カードに応じた割引をテストする

本番環境でプロモーションを有効にする前に、 動的Webhookのチェック項目 を完了し、カード入力のフローを検証してください。

このセクションで