メインコンテンツへスキップ
すべてのシステムが正常に動作しています変更履歴v1
ログイン

レコメンデーションエンジン

このガイドは、DEUNA レコメンデーションエンジンのルール管理に関する、商社向けのAPIを文書化しています。ルールは、条件と、優先順位付けされた支払い、不正行為、または認証プロバイダーのリスト、およびA/Bテスト用のオプションの重み付き子ルールを組み合わせたものです。ルールは、優先順位に基づいて評価され、最初に一致するルールが適用されます。

このページで
インタラクティブな例サンプルデータを使用し、APIリクエストは行いません。
本番環境
決済方法

レコメンデーションエンジン

一致するルールで評価するプロバイダー経路の順序を設定します。

Acme LATAM · 本番環境
設定レコメンデーションエンジン
アクティブ
01Adyen優先経路
02Worldpay代替経路
03Stripe代替経路
ルーティングAdyen → Worldpay → Stripe

認証#

すべてのエンドポイントは、 APIキー ヘッダーに送信される認証情報を使用します。 X-Api-Key これは唯一サポートされている認証方式です。 商人は、APIキーから識別されます。、そのため、商取引者の識別子はURLに表示されます。 …の場合に使用されます。 。

HTTP
X-Api-Key: {{DEUNA's API Key}}
X-Idempotency-Key: {{UUID v4}}
Content-Type: application/json
ヘッダー必須説明
X-Api-Keyはい。これは、環境と商取引者の範囲を決定します。
Content-Typeはいapplication/json.
X-Idempotency-Key推奨。これは、論理的なリクエストごとに生成する一意のキーです（UUIDが適しています）。同じキーでリトライすると、元の結果が返されます。これにより、ネットワークによるリトライが、重複したルールを作成したり、同じ操作を2回カウントしたりすることを防ぎます。

エンドポイントの概要#

メソッドパス目的
GET/routing/v1/rulesすべてのルール（優先順位）の一覧を表示
POST/routing/v1/rulesルールを作成
GET/routing/v1/rules/{rule_id}Get a single rule by ID
PUT/routing/v1/rules/{rule_id}ルールを完全に更新
PUT/routing/v1/rules/{rule_id}/reorderルールの優先順位を変更

パスパラメータ:

パラメータType備考
rule_idinteger数値規則の識別子。create/list 時に返される。

ルールオブジェクト#

「ルール」は、これらのエンドポイントで返され、受け入れられる主要なリソースです。

フィールドType必須説明
idintegerレスポンスのみサーバーによって割り当てられたルール識別子。
labelstringはい人間が理解できるルール名。
data_typestringはいこのルールが適用されるメソッドのファミリー: credit_card, debit_card, prepaid_card.
priorityintegerはい評価順序 - 低い順に処理し、最初のマッチが勝利 (正の数値)
statusEnumerationはいenabled, disabled, draft
is_defaultbooleanはいもし trueこのルールは、他のルールに一致しない場合に適用されるデフォルトルールです。 デフォルトルールには、 条件がなく、 トリガーを設定してはなりません。 ignore_next_rules.
triggerEnumerationはいpayment, reject、または merchant_ruleが含まれる場合があります。詳細は 条件式.
conditionsarray<Condition>、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、条件がなく、 ANDで結合された条件が必要です。 必須ですが、 is_default = true.
membersarray<Member>、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、を試す順序。 これは、 paymentに必要です (または children) のために merchant_rule; 禁止 reject.
childrenarray<Child>任意A/Bテスト（ trigger = merchant_rule).
ignore_next_rulesbooleanはいもし true、このルールに一致したら、さらに評価を停止します。Forbidden for reject およびデフォルトルールでのみ利用可能）のための重み付けされた子ブランチ。
created_at文字列 (RFC3339)レスポンスのみ作成日時

条件式

trigger意味memberschildrenignore_next_rulesis_default
payment指定されたプロバイダーへの支払い経路を設定する。必須 (1件以上)禁止サポートサポート
reject取引を完全に拒否します。禁止禁止禁止禁止
merchant_ruleグループ/支店: 会員経由 または 重み付けされた子要素子供がいる場合にのみ必要サポートサポートサポート

条件オブジェクト#

条件は、トランザクションが満たすべき要件を定義します。ルール上のすべての条件は、 AND.

フィールドType必須説明
idintegerレスポンスのみサーバーが割り当てる条件ID。
rule_optionobjectはい照合するフィールド（例： { "id": 5, "label": "currency" }。 merchant が利用できるルールオプションを使用してください; id debe ser > 0.
operatorEnumerationはい比較演算子。有効なものでなければなりません そのルールオプションについて
operandstring、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、比較対象の値(値) 常に文字列としてシリアル化されます。. 形式はオペレーターによって異なります。すべてのオペレーターで必須です。 ただし is_present, 演算子なし。
operand_typestringなしvalues （デフォルト）または list (オペランドは、UUIDで指定されたカスタムリストを参照します)。
operand_configオブジェクトnull、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、
metadata_field_name文字列 | null、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、必須 ～の場合 rule_option.id = 16 (metadata。評価に使用するメタデータキー。
metadata_field_type文字列 | null、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、必須 ～の場合 rule_option.id = 16。以下のいずれか: text, numeric.
error_codestringレスポンスのみ条件（例：リストのインポート）の非同期処理が失敗した場合に設定されます。
error_messagestringレスポンスのみ人間が理解しやすい詳細を error_code.

例：マスタカードブランドのカードとのマッチング

JSON
{
  "rule_option": { "id": 3, "label": "branch" },
  "operator": "in",
  "operand": "mastercard"
}

メンバーオブジェクト#

メンバーは、マッチングルールで使用されるプロバイダーであり、以下のような sort 注文（連鎖）。メンバーは、 1を参照 プロバイダー — a 決済プロバイダー, a 不正行為者、または 認証プロバイダー.

フィールドType必須説明
payment_provider_idinteger、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、DEUNAの決済プロバイダーID。以下のいずれかの場合に必須です。 merchant_payment_provider_id が利用可能です。
payment_provider_namestringレスポンスのみプロバイダー名（返信用）。
merchant_payment_provider_idUUID、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、商人の特定のプロバイダーとの接続情報。送信された場合、 payment_provider_id 以下の条件を満たしている必要があります。 また、送信する必要があります。
merchant_payment_provider_namestringレスポンスのみ接続名 (返信)。
fraud_providerstring、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、不正/不正防止プロバイダー名。支払いおよび認証プロバイダーのフィールドとは互いに排他的。
fraud_provider_idstringレスポンスのみ不正利用者 ID (返信)。
authentication_providerstring、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、認証プロバイダー名 (例: UNICO_ID, CYBERSOURCE_3DS). 支払いおよび不正行為プロバイダーのフィールドと競合する。
authentication_provider_idstringレスポンスのみ認証プロバイダーのID（返信）。
authentication_typeEnumeration、この場合、他のルールに一致しない場合に適用されます。 デフォルトルールには、認証方法。以下のいずれか。 3ds_authentication, 3ds_data_only, unico_id. 必須 メンバーが認証プロバイダーの場合
failoverオブジェクトnull任意
sortintegerはい連鎖順序 一意である必要があります ルール内で。
strategyEnumerationはい現在、 cascade.
capabilitiesarray<string>はい提供者の利用可能な機能、例： ["3ds"]送信 [] もし存在しない場合。
enabled3dsbooleanなし3DS認証をこの会員に対して実行するためのリクエスト（ペイロードの作成）。
post_authorizationbooleanはいただし、 不正行為 プロバイダーが設定 true, および、それが必須である必要があります。 最後の 加盟店による sort.
shadow_modebooleanはいプロバイダーを評価し、ルートへの影響を最小限に抑える（安全なテスト）。
enabledbooleanレスポンスのみプロバイダーが現在、加盟店に対して利用可能かどうか。

例 - 決済プロバイダーのメンバー

JSON
{
  "sort": 1,
  "strategy": "cascade",
  "payment_provider_id": 45,
  "merchant_payment_provider_id": "6e4c651a-3e5f-403d-af9d-6a9e9299acb8",
  "capabilities": ["3ds"],
  "post_authorization": false,
  "shadow_mode": false
}

例：不正検知プロバイダーの加盟

JSON
{
  "sort": 1,
  "strategy": "cascade",
  "fraud_provider": "CYBERSOURCE",
  "capabilities": [],
  "post_authorization": false,
  "shadow_mode": false
}

例：認証プロバイダーの加盟（フェイルオーバー機能付き）

JSON
{
  "sort": 1,
  "strategy": "cascade",
  "authentication_provider": "CYBERSOURCE_3DS",
  "authentication_type": "3ds_authentication",
  "failover": {
    "authentication_provider": "CYBERSOURCE_3DS",
    "authentication_type": "3ds_data_only"
  },
  "capabilities": [],
  "shadow_mode": false
}

A/Bテスト：トラフィックを2つのルートに分割#

A/Bテストを実施するには、2つの ルートを追加 ルール（例： children) および、それぞれにパーセンテージを割り当てる weight. エンジンは、マッチング取引のそれぞれの割合を、各ルートに送信します—例えば 70% はルート A、30% はルート B へ — したがって、実際のトラフィックに基づいて比較できます。

フィールドType必須説明
weightintegerはいこのルートに送信されるトラフィックの割合。2つのルートの重みの合計は100%でなければなりません。 100.
membersarray<Member>はいこのルートを提供するプロバイダー。

Reglas:

  • 正確に 2 routes.
  • weight 合計値 100.
  • ルールは、 ignore_next_rules: true.
  • 割り当ては 付着性のある ごとに transaction_id (取引は常に同じ経路を使用), そして使用された経路は返されます。 /triggers response.

例 — 70/30 の分割

JSON
{
  "label": "A/B test — MXN cards",
  "ignore_next_rules": true,
  "conditions": [
    { "rule_option": { "id": 5, "label": "currency" }, "operator": "in", "operand": "MXN" }
  ],
  "children": [
    {
      "weight": 70,
      "members": [
        { "sort": 1, "strategy": "cascade", "payment_provider_id": 45, "merchant_payment_provider_id": "6e4c651a-3e5f-403d-af9d-6a9e9299acb8" }
      ]
    },
    {
      "weight": 30,
      "members": [
        { "sort": 1, "strategy": "cascade", "payment_provider_id": 52, "merchant_payment_provider_id": "8b3d7c90-1a2b-4c3d-9e0f-5a6b7c8d9e01" }
      ]
    }
  ]
}

ルールを作成#

POST /routing/v1/rules

以下の例は、 merchant_rule マスタカードのMXN建てのクレジットカード決済の場合、不正チェックを実行し、その後分岐します。 fraud_risk: ブロック highまた、ルーティング medium/low Cybersourceへの連携

cURL

curl -X POST 'https://api.sandbox.deuna.io/routing/v1/rules' \
  -H 'X-Api-Key: {{API KEY}}' \
  -H 'X-Idempotency-Key: b3f1c2d4-9a8e-4c11-bb77-2e5f9c74a6b1' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "MX Mastercard — Cybersource",
    "priority": 2,
    "status": "enabled",
    "trigger": "merchant_rule",
    "is_default": false,
    "data_type": "credit_card",
    "ignore_next_rules": true,
    "conditions": [
      { "rule_option": { "id": 3, "label": "branch" }, "operator": "in", "operand": "mastercard" },
      { "rule_option": { "id": 5, "label": "currency" }, "operator": "in", "operand": "MXN" }
    ],
    "members": [
      { "sort": 1, "strategy": "cascade", "fraud_provider": "CYBERSOURCE" }
    ],
    "children": [
      { "conditions": [ { "rule_option": { "id": 15 }, "operator": "eq", "operand": "high" } ], "members": [] },
      { "conditions": [ { "rule_option": { "id": 15 }, "operator": "eq", "operand": "medium" } ],
        "members": [ { "sort": 1, "strategy": "cascade", "payment_provider_id": 45, "merchant_payment_provider_id": "6e4c651a-3e5f-403d-af9d-6a9e9299acb8", "capabilities": ["3ds"], "enabled3ds": false } ] },
      { "conditions": [ { "rule_option": { "id": 15 }, "operator": "eq", "operand": "low" } ],
        "members": [ { "sort": 1, "strategy": "cascade", "payment_provider_id": 45, "merchant_payment_provider_id": "6e4c651a-3e5f-403d-af9d-6a9e9299acb8", "capabilities": ["3ds"], "enabled3ds": false } ] }
    ]
  }'

応答 201

JSON
{
  "id": 21866,
  "label": "MX Mastercard — Cybersource",
  "data_type": "credit_card",
  "priority": 2,
  "status": "enabled",
  "is_default": false,
  "trigger": "merchant_rule",
  "conditions": [
    {
      "id": 44264,
      "rule_option": { "id": 3, "label": "branch" },
      "operator": "in",
      "operand_config": null,
      "operand": "mastercard",
      "operand_type": "values",
      "metadata_field_name": null,
      "metadata_field_type": null,
      "error_code": "",
      "error_message": ""
    },
    {
      "id": 44265,
      "rule_option": { "id": 5, "label": "currency" },
      "operator": "in",
      "operand": "MXN",
      "operand_type": "values"
    }
  ],
  "members": [
    {
      "payment_provider_name": null,
      "merchant_payment_provider_name": null,
      "fraud_provider": "CYBERSOURCE",
      "sort": 1,
      "capabilities": [],
      "strategy": "cascade",
      "post_authorization": false,
      "shadow_mode": false
    }
  ],
  "ignore_next_rules": true,
  "created_at": "2026-07-08T01:07:29.439794Z"
}

Get a rule by ID#

GET /routing/v1/rules/{rule_id}

単一のルールを返します。ルールには、その設定が含まれます。 conditions, members および、それらすべて children. rule_id これは数値識別子です。

cURL

curl 'https://api.sandbox.deuna.io/routing/v1/rules/21866' \
  -H 'X-Api-Key: {{API KEY}}'

応答 200

JSON
{
  "id": 21866,
  "label": "MX Mastercard — Cybersource",
  "data_type": "credit_card",
  "priority": 2,
  "status": "enabled",
  "is_default": false,
  "trigger": "merchant_rule",
  "conditions": [
    {
      "id": 44269,
      "rule_option": { "id": 3, "label": "branch" },
      "operator": "in",
      "operand": "mastercard",
      "operand_type": "values"
    },
    {
      "id": 44270,
      "rule_option": { "id": 5, "label": "currency" },
      "operator": "in",
      "operand": "MXN",
      "operand_type": "values"
    }
  ],
  "members": [
    {
      "fraud_provider_id": "3",
      "fraud_provider": "CYBERSOURCE",
      "sort": 1,
      "capabilities": [],
      "enabled": true,
      "strategy": "cascade",
      "post_authorization": false,
      "shadow_mode": false
    }
  ],
  "ignore_next_rules": true,
  "created_at": "2026-07-08T01:07:29.439794Z",
  "children": [
    {
      "conditions": [
        { "id": 44271, "rule_option": { "id": 15, "label": "fraud_risk" }, "operator": "eq", "operand": "high", "operand_type": "values" }
      ],
      "members": [],
      "ignore_next_rules": true
    },
    {
      "conditions": [
        { "id": 44272, "rule_option": { "id": 15, "label": "fraud_risk" }, "operator": "eq", "operand": "medium", "operand_type": "values" }
      ],
      "members": [
        {
          "payment_provider_id": 45,
          "payment_provider_name": "cybersource",
          "merchant_payment_provider_id": "6e4c651a-3e5f-403d-af9d-6a9e9299acb8",
          "merchant_payment_provider_name": "Cybersource MX",
          "sort": 1,
          "capabilities": ["3ds"],
          "enabled": true,
          "strategy": "cascade",
          "post_authorization": false,
          "shadow_mode": false
        }
      ],
      "ignore_next_rules": true
    }
  ]
}

Ошибки: PAYROU-NOT_FOUND (404) – 規則が存在しない場合 PAYROU-FORBIDDEN (403) アクセスできない場合; PAYROU-INVALID_PATH_PARAM (400) の場合 rule_id 有効な整数ではありません。

ルール一覧#

GET /routing/v1/rules

貴社のルールを返します 優先順位. 結果は ページネーション 不透明なカーソルとともに。

クエリパラメータType説明
limitintegerオプション。ページサイズ。デフォルト 50, 最大 200.
cursorstringオプション。以前の応答からの非表示カーソル。 pagination.next_cursor. 最初のページでは省略
payment_provider_idintegerオプション。この支払いプロバイダーを参照するルールのみを返します。

レスポンスは、ルールをまとめた pagination オブジェクトを繰り返しリクエストする。 next_cursor ～ has_more 経由で提供されます。 true.

pagination このフィールドにはType説明
next_cursor文字列 | null次のページへのカーソル、または null 最後のページで。
has_morebooleantrue 追加のルールが利用可能な場合。
limitinteger適用されたページサイズ。

cURL

curl 'https://api.sandbox.deuna.io/routing/v1/rules?limit=50' \
  -H 'X-Api-Key: {{API KEY}}'

応答 200

JSON
{
  "merchant_id": "87dd2c00-1f7a-44aa-9e05-34330bab73cc",
  "pagination": {
    "next_cursor": "eyJwcmlvcml0eSI6M30",
    "has_more": true,
    "limit": 50
  },
  "rules": [
    {
      "id": 21873,
      "label": "MX Mastercard — Cybersource",
      "data_type": "credit_card",
      "priority": 2,
      "status": "enabled",
      "is_default": false,
      "trigger": "payment",
      "conditions": [
        { "id": 44274, "rule_option": { "id": 3, "label": "branch" }, "operator": "in", "operand": "mastercard", "operand_type": "values" }
      ],
      "members": [
        {
          "payment_provider_id": 45,
          "payment_provider_name": "cybersource",
          "merchant_payment_provider_id": "6e4c651a-3e5f-403d-af9d-6a9e9299acb8",
          "merchant_payment_provider_name": "Cybersource MX",
          "sort": 1,
          "capabilities": ["3ds"],
          "enabled": true,
          "strategy": "cascade",
          "post_authorization": false,
          "shadow_mode": false
        }
      ],
      "ignore_next_rules": true,
      "created_at": "2026-07-08T01:09:49.553614Z"
    }
  ]
}

ルールを更新する#

PUT /routing/v1/rules/{rule_id}

ルールを完全に置き換える。完全なルール本体（作成時と同じ形式）を送信してください。 id および created_at。一般的な用途：スワップ status ～の間 enabled および disabled （これはルールを削除する代わりに「無効化」する方法です）。

cURL – ルールを無効化する

curl -X PUT 'https://api.sandbox.deuna.io/routing/v1/rules/21866' \
  -H 'X-Api-Key: {{API KEY}}' \
  -H 'X-Idempotency-Key: 7c2e5a19-4b8d-4f10-9a3c-1d2e3f4a5b6c' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 21866,
    "created_at": "2026-07-08T01:07:29.439794Z",
    "label": "MX Mastercard — Cybersource",
    "priority": 2,
    "status": "disabled",
    "trigger": "merchant_rule",
    "is_default": false,
    "data_type": "credit_card",
    "ignore_next_rules": true,
    "conditions": [
      { "id": 44264, "rule_option": { "id": 3, "label": "branch" }, "operator": "in", "operand": "mastercard", "operand_type": "values" },
      { "id": 44265, "rule_option": { "id": 5, "label": "currency" }, "operator": "in", "operand": "MXN", "operand_type": "values" }
    ],
    "members": [
      { "sort": 1, "strategy": "cascade", "fraud_provider": "CYBERSOURCE", "capabilities": [], "post_authorization": false, "shadow_mode": false }
    ]
  }'

応答 200

更新されたルールを返します status 現在 disabled。注：条件 idは更新時に再発行されます。

ルールの優先度を変更（並び替え）#

PUT /routing/v1/rules/{rule_id}/reorder

ルールを新しい優先度に変更します。他のルールもそれに従って再順序されます。

cURL

curl -X PUT 'https://api.sandbox.deuna.io/routing/v1/rules/21873/reorder' \
  -H 'X-Api-Key: sk_sandbox_9f8b2c1a7d4e60b3' \
  -H 'Content-Type: application/json' \
  -d '{ "priority": 2 }'
フィールドType必須制約
priorityintegerはいNon-negative integer

応答 200

JSON
{ "priority": 2 }

Ошибки: PAYROU-VALIDATION (400) を返す errors[].code = PRIORITY_OUT_OF_RANGE 、もし priority は、非負の整数ではありません。

検証#

作成および更新時に、これらのチェックを実行します。 失敗した場合、HTTP エラーを返します。 400 トップレベルのコード PAYROU-VALIDATION および、違反する各フィールドごとに1つのエントリ errors[] (ver エラー （封筒および、詳細なフィールドレベルのコードカタログを含む）

ルールレベル

  • status 必須の選択肢は以下のいずれかです enabled, disabled, draft, process-in-background.
  • trigger 必須の選択肢は以下のいずれかです payment, reject, merchant_rule.
  • trigger = payment → 少なくとも1人の成人会員、未成年者不可。
  • trigger = reject → メンバーなし、子なし ignore_next_rules は「false」である必要があります。 is_default は「偽」である必要があります。
  • trigger = merchant_rule → 少なくとも1人のメンバー または 少なくとも1人の子供。
  • is_default = true → 条件なしで ignore_next_rules は「偽」である必要があります。
  • is_default = false → 少なくとも1つの条件を満たす必要があります。
  • priority debe ser > 0 および ≤ 1000.

条件

  • rule_option.id 必須 (> 0); operand 必須（空でない）。
  • operator 有効であること そのルールオプションについて (詳細はカタログを参照)。
  • A rule_option （ただし、 metadata).
  • For metadata (ID 16) の場合のみ適用されます。 metadata_field_name および metadata_field_type 必須項目で、タイプは text または numeric.
  • For operand_type = list: operand 有効なリスト UUID であり、存在する必要があります。

メンバー

  • 各メンバーは、以下のいずれかのプロバイダータイプを必ず指定する必要があります：決済、商社決済、不正検知、または認証。
  • 同一の加盟店には、異なる種類の決済プロバイダーを使用することはできません。
  • もし merchant_payment_provider_id 以下のいずれかの条件を満たす必要があります。 payment_provider_id も必要です。
  • メンバー認証には、以下のものが必要です。 authentication_type (DEUNA の一機能) 3ds_authentication, 3ds_data_only, unico_id).
  • failover は有効 のみ メンバー認証時に使用可能 authentication_type また、有効な値である必要があります。
  • sort この値は、ルール内で一意である必要があります。
  • 「提供者」は、ルールごとに1回しか登場できません。
  • strategy debe ser cascade.
  • post_authorization = true 不正検知プロバイダーにのみ適用され、そのメンバーは 最後の 作者 sort.

サービスレベル（商社設定との照合）

  • 参照されるルールオプションが存在し、指定されたオペレーターをサポートしている必要があります。
  • 参照される決済/商社決済/不正検知/認証プロバイダーは、商社向けに有効になっている必要があります。
  • merchant_payment_provider_id 必須は、指定された payment_provider_id.

エラー#

エラーヘッダー

すべてのエラーレスポンスは、同じJSON形式を使用します:

JSON
{
  "code": "PAYROU-VALIDATION",
  "message": "One or more fields failed validation.",
  "request_id": "req_01J9Z8K7QF3M2N4P5R6S7T8U9V",
  "errors": [
    {
      "field": "members",
      "code": "MEMBERS_REQUIRED",
      "message": "At least one member is required when trigger is 'payment'."
    }
  ]
}
フィールドType説明
codestring安定した、機械可読な上位レベルのコード。 このブランチでは、on では絶対にありませんmessage.
messagestring人間が理解できる概要。必要に応じて言い換えたり、ローカライズしたりできます。解析しないでください。
request_idstringレスポンスごとに一意であり、また以下にも返されます。 X-Request-Id レスポンスヘッダー（成功時） および エラー。サポートリクエストで引用してください。
errorsarrayMostrar solo para PAYROU-VALIDATION1つのフィールドにつき1つのエントリ。
errors[].fieldstringフィールドへのパスを、ドット/ブラケット表記で指定します（例： priority, conditions[1].operand, members[0].sort.
errors[].codestring安定したフィールドレベルのコード (詳細は の検証コードを参照)).
errors[].messagestring人間が理解しやすい詳細情報。解析は不要。

書き込み時には、必ず X-Idempotency-Key を送信してください。同じキーを再利用すると、元のレスポンスが返されます。異なる を持つキーを再利用すると、 body が返されます 409 PAYROU-CONFLICT.

HTTPステータスコード

Estado意味
200 / 201Success.
400リクエストが無効です。検証に失敗、不正なJSON、または無効なパス/クエリパラメータが指定されています。
401認証 失敗しました。 X-Api-Key 指定された値が欠落しているか無効です。
403認証 エラー – キーは有効ですが、この商取引/リソースへのアクセスは許可されていません。
404指定されたルールまたは参照されているリソースが存在しません。
409競合 – 異なる本文で、または同時更新により、一意キーが再利用されています。
429レート制限を超えました – 以下の手順で再試行してください。 Retry-After header.
500予期せぬサーバーエラー。
503下流の依存関係が一時的に利用できない – タイムアウト後に再試行可能。

上位レベルのコード

コードHTTPいつ
PAYROU-VALIDATION4001つ以上のフィールドが検証に失敗しました。詳細は、 errors[].
PAYROU-MALFORMED_JSON400リクエストボディが有効なJSONではありません。
PAYROU-INVALID_PATH_PARAM400パスパラメータの型/形式が正しくない (例: 整数ではない) rule_id).
PAYROU-INVALID_QUERY_PARAM400クエリパラメータが無効 (例: limit 範囲外、無効な形式 cursor).
PAYROU-UNAUTHENTICATED401APIキーの欠落または無効。
PAYROU-FORBIDDEN403有効なキーですが、この商社/リソースには適用されません。
PAYROU-NOT_FOUND404ルールまたは参照されたリソースが見つかりません。
PAYROU-CONFLICT409異なるペイロードを使用した、または同時による同一性のキーの再利用。
PAYROU-RATE_LIMITED429リクエスト数が多すぎます。
PAYROU-INTERNAL500予期せぬサーバーエラー。
PAYROU-UPSTREAM_UNAVAILABLE503下流の依存関係が一時的に利用できません。

検証コード

返される errors[] トップレベルのコードが PAYROU-VALIDATION. 各バージョンは安定しており、ブランチングに適しています。

ルールレベル

code一般的な field原因
INVALID_STATUSstatus～ではない enabled, disabled, draft, process-in-background.
INVALID_TRIGGERtrigger～ではない payment, reject, merchant_rule.
PRIORITY_OUT_OF_RANGEpriority指定期間外 1 および 1000 」と「 ≤ 0 および > 1000).
MEMBERS_REQUIREDmemberstrigger = payment 」の両方をカバーし、いずれにもメンバーがいない状態を指します。)
MEMBERS_OR_CHILDREN_REQUIREDmemberstrigger = merchant_rule メンバーも子供もいない状態。
CONDITIONS_REQUIREDconditionsデフォルトではないルールで、条件が設定されていない。
TRIGGER_CANNOT_BE_DEFAULTis_defaultreject 条件付きルール。 is_default = true.
TRIGGER_CANNOT_HAVE_MEMBERSmembersreject メンバーを持つルール。
TRIGGER_CANNOT_HAVE_CHILDRENchildrenpayment/reject 子を持つルール。
TRIGGER_CANNOT_IGNORE_NEXT_RULESignore_next_rulesreject 条件付きルール。 ignore_next_rules = true.
DEFAULT_RULE_CANNOT_HAVE_CONDITIONSconditionsデフォルトルールと条件
DEFAULT_RULE_CANNOT_IGNORE_NEXT_RULESignore_next_rulesデフォルトのルールで、 ignore_next_rules = true.

条件

code一般的な field原因
RULE_OPTION_ID_REQUIREDconditions[i].rule_option.id欠落している、または ≤ 0.
OPERAND_REQUIREDconditions[i].operand必須の演算子にオペランドが設定されていない。
OPERATOR_REQUIREDconditions[i].operator演算子が設定されていない。
INVALID_OPERATORconditions[i].operatorそのルールオプションには、指定された演算子が使用できない。
DUPLICATE_RULE_OPTIONconditions[i].rule_option同じオプションを複数回使用（ただし metadata).
METADATA_FIELDS_REQUIREDconditions[i].metadata_field_namemetadata 条件が欠落している。 metadata_field_name/metadata_field_type.
INVALID_METADATA_FIELD_TYPEconditions[i].metadata_field_typeいいえ text または numeric.
RULE_OPTION_NOT_FOUNDconditions[i].rule_option.idルールオプションが存在しない。
INVALID_LIST_REFERENCEconditions[i].operandoperand_type = list ただし、リストのUUIDが無効であるか、見つからない。

メンバー

code一般的な field原因
MEMBER_PROVIDER_REQUIREDmembers[i]メンバーが、支払い、不正検知、または認証のいずれのプロバイダーも参照していない。
MEMBER_MULTIPLE_PROVIDER_TYPESmembers[i]メンバーが複数のプロバイダータイプを混在している（例：支払い + 不正検知、または支払い + 認証）。
PAYMENT_PROVIDER_ID_REQUIREDmembers[i].payment_provider_idmerchant_payment_provider_id 送信時に payment_provider_id.
AUTHENTICATION_TYPE_REQUIREDmembers[i].authentication_type認証されていないメンバーの認証を無効化する authentication_type.
INVALID_AUTHENTICATION_TYPEmembers[i].authentication_type～ではない 3ds_authentication, 3ds_data_only, unico_id （これは failover.authentication_type にも適用されます）。
FAILOVER_ONLY_ON_AUTHENTICATIONmembers[i].failoverfailover 認証されていないメンバーに対して設定する。
DUPLICATE_MEMBERmembers[i]同じプロバイダーがルール内で複数回登場する。
DUPLICATE_MEMBER_SORTmembers[i].sort2つのメンバーが同じ sort value.
INVALID_STRATEGYmembers[i].strategyいいえ cascade.
POST_AUTH_ONLY_FRAUDmembers[i].post_authorizationpost_authorization = true 不正なメンバーに対して。
POST_AUTH_MUST_BE_LASTmembers[i].post_authorization次の post_authorization メンバーが最後に設定されていることを確認する。 sort.
PROVIDER_NOT_AVAILABLEmembers[i]（支払い、不正検知、または認証）プロバイダーがこの商に対して有効になっていない。
MERCHANT_PROVIDER_MISMATCHmembers[i].merchant_payment_provider_id接続が指定された payment_provider_id.

A/Bテスト

code一般的な field原因
SPLIT_WEIGHTS_MUST_SUM_TO_100children子 weight 値の合計が… 100.

エンドツーエンドフロー#

次の /triggers エンドポイントは 2つの統合モードをサポート — どのオプションを選択するかは、どの程度の決定ロジックを所有したいかによって選択してください。どちらも同じエンドポイントと、同じルールを使用します。応答形式と呼び出し回数のみが異なります。以下の方法で選択してください。 mode リクエスト（single がデフォルト）。どちらの方法でも、1つの /feedback call.

モードでプロセスを完了できます仕組み以下の状況で有効
1 · 1回の呼び出し (クライアント主導型)1 /triggers 1回の呼び出しで 完全なプラン — 認証プロセス（フェイルオーバー機能付き）の実行 actions 以下に、それぞれの結果に対応するマッピングを定義します。 process または 拒否. 計画を実行するのはご自身で行います。ラウンドトリップを最小限に抑え、ローカルで決定を適用することに満足しています。
2 · ガイド (エンジン駆動型)を呼び出す /triggers およびエンジンは、以下を返します。 次へ さらに status. 実行後、呼び出し /triggers 再び、そのステップの結果を確認します。エンジンは次のステップを返します。これを繰り返すまで。 status = completed.DEUNAが、段階的に、決済処理の意思決定を所有し、一元化することを希望します。

モード 1 – 単一呼び出し

あなたは 単一 /triggers 呼び出し。DEUNAの前に詐欺プロバイダーを実行する場合は、その結果をこの呼び出しに含めてください。レスポンスは自律的です。認証を実行するものを指定します（3DS & auth 3DSの結果）。 フェイルオーバー （プライマリが利用できない場合）および、 操作 これにより、認証結果に基づいて、次に実行するアクションを決定できます。 process 決済プロバイダーとの連携において、 拒否. 貴社のプラットフォームは、その計画をローカルで実行し、1つの処理で完了します。 /feedback 呼び出し — 存在します なし秒 /triggers round ストリップ.

段階的な手順

  1. (任意) 不正行為の疑いのあるプロバイダーとの連携。 もし、設定で事前に不正検知プロバイダーを使用している場合、そのスコア/決定を記録し、ルールとの照合に使用できるようにします（ fraud_risk オプションまたは metadata).
  2. 推奨の取得（1回の呼び出し）。 POST /routing/v1/triggers トランザクションデータ（および、該当する場合の不正検出結果）とともに。 応答には、 authentication ブロック（primary + オプション failover）と、 actions block.
  3. Authenticate. 推奨される認証を実行します（例：3DS認証、3DSデータのみ、またはUnico ID）。 primary 支払いプロバイダーが利用できない場合、以下の手順に従ってください。 failover.
  4. 決定し、処理を実行します。 適用 actions: 各結果は以下に対応します process （指定された支払いプロバイダーを使用）または decline; それ default この動作は、他の条件に合致しない場合に適用されます。
  5. 結果を報告してください。 POST /routing/v1/feedback 「with」 collection オブジェクトと attempts (認証結果 + 決済結果)。これにより、分析と機械学習のラベル付けのためのプロセスが完了します。

単一の決済プロバイダーを使用する店舗は、 process アクション：複数の加盟店は、ルールの連鎖設定を構成できます。 membersи рекомендация отражает поставщиков, которые следует попробовать.

シーケンス図
1Your platform2Fraud provider3DEUNA RecommendationEnginescore request (if used)score + decisionOne POST /routing/v1/triggers (txndata + fraud result)recommendation (auth route + failover+ actions)Run recommended auth use failover ifprimary downApply actions - process with paymentprovider, or declineTwo POST /routing/v1/feedback (authresult + payment result)200 OK (outcome recorded, predictionML labeled)
商社または顧客プロバイダーまたはプロセッサDEUNA

モード1の応答 – 計画全体

次の /triggers 応答は、単一で独立した推奨事項です： authentication 実行 (オプションで) failover) および actions これらは、認証結果に基づいて実行するアクションを定義します。この処理は、プラットフォーム内で実行されます。

JSON
{
  "collection": {
    "id": "c7b9e3a2-4d51-4f8a-9b21-6e0f2a1c8d34",
    "prediction_id": "pred_xyz789abc"
  },
  "recommendation": {
    "rule_id": 21866,
    "rule_label": "High risk → 3DS authentication",
    "authentication": {
      "primary":  { "authentication_type": "3ds_authentication" },
      "failover": { "authentication_type": "3ds_data_only" }
    },
    "actions": {
      "on_success_with_liability_shift": { "action": "process", "provider": "acquirer_gateway" },
      "default": { "action": "decline" }
    }
  }
}
フィールドType説明
collection.idUUIDこの評価の相関ID。これを繰り返してください。 /feedback.
collection.prediction_idstring推奨のためのMLハンドル。これを /feedback.
recommendation.rule_idinteger一致したルールを反映します（ルールオブジェクトの同じ識別子）。同じ id).
recommendation.rule_labelstring人間が理解できるルール名。
recommendation.authentication.primaryobjectまず実行する必要がある認証: { "authentication_type": "3ds_authentication" }を使用します。 authentication_type ルールメンバーとして設定する値。
recommendation.authentication.failoverオブジェクトnull
recommendation.actionsobject認証結果をアクションにマッピングします。結果に基づいてキー付けられます。
recommendation.actions.<outcome>.actionEnumerationprocess または decline.
recommendation.actions.<outcome>.providerstring以下の条件で action = process — 使用する決済プロバイダーの名前（ルールで構成されています。例： acquirer_gateway).
recommendation.actions.defaultobjectその他の結果キーと一致しない場合に適用されるフォールバックアクション。

「Outcome keys」は、 actions 適用される認証結果を記述します（例： on_success_with_liability_shift); default として、すべてのケースに対応します。

モード 2 — 手動 (段階的な)

設定 "mode": "guided" での処理。フルな手順ではなく、エンジンは必要な 次へ と statusのみを返し、ユーザーは手順を一つずつ実行します。

  • status: awaiting_authentication → next_step は、実行する認証の種類を指定します。
  • status: awaiting_fraud → next_step は、実行する不正チェックの種類を指定します。
  • status: completed → エンジンが決定します。 next_step.action 経由で提供されます。 process （ provider) または decline.

手順を実行した後、次の API を呼び出します。 /triggers 再度、 echo の collection を前のレスポンスから取得し、その手順の結果（authentication_result または fraud_result）を含めます。エンジンは次の手順に進み、結果を返します。これを繰り返すまで status = completedその後、処理を完了します。 /feedback.

シーケンス図
1Your platform(merchant / PSP)2DEUNA RecommendationEnginePOST /routing/v1/triggers(mode=guided, txn data)status=awaiting_authentication ·next_step: run 3ds_authenticationRun 3DS authenticationPOST /routing/v1/triggers (collection+ authentication_result)status=completed · next_step: processwith acquirer_gatewayProcess the paymentPOST /routing/v1/feedback (attempts)200 OK
商社または顧客DEUNA

最初のレスポンス – 処理を実行するためのステップ

JSON
{
  "collection": { "id": "c7b9e3a2-4d51-4f8a-9b21-6e0f2a1c8d34", "prediction_id": "pred_xyz789abc" },
  "recommendation": {
    "rule_id": 21866,
    "status": "awaiting_authentication",
    "next_step": {
      "type": "authentication",
      "authentication_type": "3ds_authentication",
      "failover": { "authentication_type": "3ds_data_only" }
    }
  }
}

フォローアップリクエスト – ステップの結果を送信

JSON
{
  "mode": "guided",
  "collection": { "id": "c7b9e3a2-4d51-4f8a-9b21-6e0f2a1c8d34", "prediction_id": "pred_xyz789abc" },
  "authentication_result": { "eci": "05", "pares_status": "Y", "liability_shift": true }
}

ターミナル応答 — status = completed

JSON
{
  "collection": { "id": "c7b9e3a2-4d51-4f8a-9b21-6e0f2a1c8d34", "prediction_id": "pred_xyz789abc" },
  "recommendation": {
    "rule_id": 21866,
    "status": "completed",
    "next_step": { "type": "process", "provider": "acquirer_gateway" }
  }
}
フィールドType説明
modeEnumerationリクエストフィールド: single （デフォルト）または guided.
collectionobjectリクエストフィールド：フォローアップガイダンスコールでのエコー collection 前回の回答の続きで、同様の評価を継続します。
authentication_result / fraud_resultobjectリクエストフィールド: 直前に実行したステップの結果。
recommendation.statusEnumerationawaiting_authentication, awaiting_fraud、または completed.
recommendation.next_step.typeEnumerationauthentication, fraud, process、または decline.
recommendation.next_step.authentication_typeEnumeration以下の条件で type = authentication.
recommendation.next_step.failoverオブジェクトnull
recommendation.next_step.providerstring以下の条件で type = process — 使用する決済プロバイダー。

両方のモードは同じルールに基づいて動作し、同じ結果を生成します。ガイドモードは、事前に全体の計画ではなく、段階的にDEUNAにリクエストを送信します。

カードの識別を開始 /triggers

カード payment_source.card_info pueden ser proporcionadas 3つの方法のいずれか:

メソッドフィールド備考
フル PANcard_numberBIN とブランドはサーバー側で取得されます。
BIN + 最後の4桁bin (8桁)、 last_fourフルなPANを送信しない場合に利用。8桁のBINは発行元レベルのルーティングを提供します。
ネットワークトークンnetwork_token: { dpan, par, account_bin, cryptogram, eci }トークン化された認証情報の場合。BIN レベルのデータを取得する方法に関する注を参照してください。

フィードバック attempts 例

attempts 実際に何が起こったかを報告します: 認証結果、および、お使いの決済プロバイダからの支払い結果（ISO 8583コード）。

JSON
{
  "collection": { "id": "c7b9e3a2-4d51-4f8a-9b21-6e0f2a1c8d34", "prediction_id": "pred_xyz789abc" },
  "transaction_id": "1b3d5f7a-8c9e-40a2-b1c3-d4e5f6a7b8c9",
  "attempts": [
    {
      "step": "authentication",
      "authentication_type": "3ds_authentication",
      "result": { "eci": "05", "pares_status": "Y", "liability_shift": true }
    },
    {
      "step": "payment",
      "provider": "acquirer_gateway",
      "result": { "status": "declined", "error_code": "05", "error_reason": "do_not_honor" }
    }
  ]
}

error_code * "05" = を遵守しません. eci および pares_status 3DS の結果を伝送する必要はありません。 liability_shift 認証の責任移転を指示します。

バックアップ認証（フェイルオーバー）

ルールは、以下のようなものを定義できます。 フェイルオーバー 認証プロバイダー。推奨される primary プロバイダーが利用できない場合（例：3DS認証プロバイダーがダウン）、推奨される処理は、 failover (例：3DS データのみ) を利用することで、プロバイダーの障害がトランザクションの認証を妨げることはありません。

ご質問や詳細が不足している場合は、DEUNAの統合チームにお問い合わせください。