Motore di raccomandazione

Definisci il percorso ordinato dei provider valutato per una regola corrispondente.

Acme LATAM · Produzione

ConfigurazioneMotore di raccomandazione

Attiva

01AdyenPercorso principale

02WorldpayPercorso alternativo

03StripePercorso alternativo

InstradamentoAdyen → Worldpay → Stripe

Autenticazione#

Tutti gli endpoint autenticano con un Chiave API inviato nel X-Api-Key header — questo è l'unico schema di autenticazione supportato. Il tuo commerciante è risolto dalla chiave API, così l'identificatore commerciante fa non non non lo so appaiono nell'URL.

HTTP

X-Api-Key: {{DEUNA's API Key}}
X-Idempotency-Key: {{UUID v4}}
Content-Type: application/json

Intestazione	Obbligatorio	Descrizione
`X-Api-Key`	Sì.	La chiave API. Determina l'ambiente e la portata del commerciante.
`Content-Type`	Sì.	`application/json`.
`X-Idempotency-Key`	Raccomandazioni	Una chiave unica che si genera per richiesta logica (un UUID funziona bene). Ripensando con la stessa chiave restituisce il risultato originale invece di applicare l'operazione due volte — inviarlo così retries di rete non creare regole duplicate o doppio conteggio un'azione.

Riepilogo del punto di vista#

Metodo	Sentiero	Oggetto
`GET`	`/routing/v1/rules`	Elenca tutte le regole (ordine priorità)
`POST`	`/routing/v1/rules`	Creare una regola
`GET`	`/routing/v1/rules/{rule_id}`	Get a single rule by ID
`PUT`	`/routing/v1/rules/{rule_id}`	Aggiornare una regola (sostituire completamente)
`PUT`	`/routing/v1/rules/{rule_id}/reorder`	Cambiare la priorità di una regola

Parametri del percorso:

Parametro	Tipo	Note
`rule_id`	integer	Identificatore di regola numerico restituito da creare/list.

L'oggetto della Regola#

Una regola è la risorsa principale restituita e accettata da questi endpoint.

Campo	Tipo	Obbligatorio	Descrizione
`id`	integer	Risposta solo	Identificatore di regola assegnato dal server.
`label`	string	Sì.	Nome di regola leggibile dall'uomo.
`data_type`	string	Sì.	Metodo famiglia questa regola si applica a: `credit_card`, `debit_card`, `prepaid_card`.
`priority`	integer	Sì.	Ordine di valutazione — prima corsa, prima vittoria partita (numeri non negativi)
`status`	enumera	Sì.	`enabled`, `disabled`, `draft`
`is_default`	boolean	Sì.	Se `true`, questa è la regola di fallback quando nessun altro corrisponde. Una regola predefinita deve avere No. condizioni e non deve essere impostata `ignore_next_rules`.
`trigger`	enumera	Sì.	`payment`, `reject`o `merchant_rule`. Vedi Triggers.
`conditions`	array<Condition>	Condizionamenti	Criteri di corrispondenza, E-combinato. Richiesto a meno che `is_default = true`.
`members`	array<Member>	Condizionamenti	I fornitori hanno ordinato di tentare. Obbligatorio `payment`; richiesto (o `children`) per `merchant_rule`; vietato per `reject`.
`children`	array<Child>	Facoltativo	Bracciali per bambini ponderati per test A/B (solo con `trigger = merchant_rule`).
`ignore_next_rules`	boolean	Sì.	Se `true`, smettere di valutare altre regole una volta che questo corrisponde. Proibita `reject` e per regole di default.
`created_at`	stringa (RFC3339)	Risposta solo	Tempi di creazione.

Triggers

`trigger`	Significato	`members`	`children`	`ignore_next_rules`	`is_default`
`payment`	Percorso del pagamento ai fornitori elencati.	Richiesto (≥1)	Non consentito	Consentito	Consentito
`reject`	Bloccate la transazione.	Non consentito	Non consentito	Non consentito	Non consentito
`merchant_rule`	Gruppo/branch: percorso attraverso i membri o bambini ponderati.	Richiesto se non bambini	Consentito	Consentito	Consentito

L'oggetto Condizione#

Le condizioni definiscono ciò che una transazione deve corrispondere. Tutte le condizioni su una regola sono combinate con AND.

Campo	Tipo	Obbligatorio	Descrizione
`id`	integer	Risposta solo	ID stato assegnato dal server.
`rule_option`	object	Sì.	Il campo da abbinare, per esempio `{ "id": 5, "label": "currency" }`. Utilizzare un'opzione di regola disponibile al commerciante; `id` deve essere `> 0`.
`operator`	enumera	Sì.	Operatore di confronto. Deve essere valido per quella opzione di regola
`operand`	string	Condizionamenti	Il valore(i) da confrontare contro, sempre serializzato come una stringa. Formato dipende dall'operatore. Richiesto per ogni operatore eccetto `is_present`, che non richiede alcun operando.
`operand_type`	string	No.	`values` (predefinito) o `list` (operare fa riferimento ad una lista personalizzata di UUID).
`operand_config`	oggetto \| null	Condizionamenti	Usato quando `operand_type = list`: `{ "custom_list": { "field_to_evaluate": "email" } }`.
`metadata_field_name`	stringa \| null	Condizionamenti	Obbligatorio quando `rule_option.id = 16` (`metadata`). La chiave dei metadati per valutare.
`metadata_field_type`	stringa \| null	Condizionamenti	Obbligatorio quando `rule_option.id = 16`. Uno di `text`, `numeric`.
`error_code`	string	Risposta solo	Impostare quando l'elaborazione asincrona di una condizione (ad esempio l'importazione di elenco) non è riuscita.
`error_message`	string	Risposta solo	Dettaglio leggibile per l'uomo `error_code`.

Esempio — corrispondenza carte di marca Mastercard

JSON

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

Oggetto#

I membri sono i fornitori che utilizzano una regola corrispondente, tentati sort ordine (la cascata). Riferimenti di un membro uno fornitore — un fornitore di pagamento- Un'altra volta. fornitore di frodio un provider di autenticazione.

Campo	Tipo	Obbligatorio	Descrizione
`payment_provider_id`	integer	Condizionamenti	ID fornitore di pagamento DEUNA. Se necessario `merchant_payment_provider_id` Strumento e dati di connessione usati per elaborare il pagamento.
`payment_provider_name`	string	Risposta solo	Nome del fornitore (ritorno riecheggiato).
`merchant_payment_provider_id`	UUID	Condizionamenti	La connessione specifica del fornitore di Merchant. Se inviato, `payment_provider_id` deve essere anche essere inviato.
`merchant_payment_provider_name`	string	Risposta solo	Nome di connessione (ritorno riecheggiato).
`fraud_provider`	string	Condizionamenti	Nome del fornitore di frode/antifrode. Mutualmente esclusivo con i campi di pagamento- e di autenticazione-provider.
`fraud_provider_id`	string	Risposta solo	ID fornitore di frode (risolto).
`authentication_provider`	string	Condizionamenti	Nome del fornitore di autenticazione (ad es. `UNICO_ID`, `CYBERSOURCE_3DS`). Mutualmente esclusivo con i campi di pagamento- e frode-provider.
`authentication_provider_id`	string	Risposta solo	ID fornitore di autenticazione (ritorno riecheggiato).
`authentication_type`	enumera	Condizionamenti	Il metodo di autenticazione. Uno di `3ds_authentication`, `3ds_data_only`, `unico_id`. Obbligatorio quando il membro è un fornitore di autenticazione.
`failover`	oggetto \| null	Facoltativo	Autenticazione di backup utilizzata quando il fornitore primario non è disponibile: `{ "authentication_provider": "...", "authentication_type": "..." }`. Valido solo solo sui membri del fornitore di autenticazione.
`sort`	integer	Sì.	Ordine Cascade. Deve essere unico all'interno della regola.
`strategy`	enumera	Sì.	Attualmente solo `cascade`.
`capabilities`	array<string>	Sì.	Capacità del fornitore da usare, ad esempio. `["3ds"]`. Invia `[]` se non ne ha.
`enabled3ds`	boolean	No.	Richiedi l'autenticazione 3DS su questo membro (creare payload).
`post_authorization`	boolean	Sì.	Solo un frode provider può impostare `true`e deve essere Ultimo ultimo membro `sort`.
`shadow_mode`	boolean	Sì.	Valutare il fornitore senza influenzare la rotta (prova sicura).
`enabled`	boolean	Risposta solo	Se il fornitore è attualmente disponibile per il commerciante.

Esempio — membro del fornitore di pagamento

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
}

Esempio — membro del gruppo di frodi

JSON

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

Esempio — membro del fornitore di autenticazione (con failover)

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
}

Test A/B — traffico diviso tra due percorsi#

Al test A/B, aggiungere due percorsi a una regola (come children) e dare a ciascuno una percentuale weight. Il motore invia quella parte delle transazioni corrispondenti a ogni percorso — ad esempio. 70% sulla Route A, 30% sulla Route B — così potete paragonarli sul traffico dal vivo.

Campo	Tipo	Obbligatorio	Descrizione
`weight`	integer	Sì.	Percentuale di traffico corrispondente inviato a questo percorso. I pesi delle due rotte devono essere sommati `100`.
`members`	array<Member>	Sì.	Il fornitore(i) per questo percorso.

Regole:

Esattamente. Due routes.
weight i valori devono essere sommati 100.
La regola deve essere impostata ignore_next_rules: true.
Assegnazione appiccicoso per transaction_id (una transazione ottiene sempre la stessa rotta), e la rotta che corre è riecheggiata nel /triggers response.

Esempio: 70/30 spaccato

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" }
      ]
    }
  ]
}

Creare una regola#

POST /routing/v1/rules

L'esempio qui sotto crea un merchant_rule per le carte di credito Mastercard in MXN, effettua un controllo delle frodi, e poi i rami da fraud_risk: blocco highe via medium/low a 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 } ] }
    ]
  }'

const response = await fetch("https://api.sandbox.deuna.io/routing/v1/rules", {
  method: "POST",
  headers: {
    "X-Api-Key": "{{API KEY}}",
    "X-Idempotency-Key": "b3f1c2d4-9a8e-4c11-bb77-2e5f9c74a6b1",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "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
          }
        ]
      }
    ]
  })
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "POST",
    "https://api.sandbox.deuna.io/routing/v1/rules",
    headers={
        "X-Api-Key": "{{API KEY}}",
        "X-Idempotency-Key": "b3f1c2d4-9a8e-4c11-bb77-2e5f9c74a6b1",
        "Content-Type": "application/json"
    },
    json={
          "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
                }
              ]
            }
          ]
        },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/routing/v1/rules",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: {{API KEY}}",
    "X-Idempotency-Key: b3f1c2d4-9a8e-4c11-bb77-2e5f9c74a6b1",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
      "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
            ]
          ]
        ]
      ]
    ])
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sandbox.deuna.io/routing/v1/rules"))
      .header("X-Api-Key", "{{API KEY}}")
      .header("X-Idempotency-Key", "b3f1c2d4-9a8e-4c11-bb77-2e5f9c74a6b1")
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("{\n    \"label\": \"MX Mastercard — Cybersource\",\n    \"priority\": 2,\n    \"status\": \"enabled\",\n    \"trigger\": \"merchant_rule\",\n    \"is_default\": false,\n    \"data_type\": \"credit_card\",\n    \"ignore_next_rules\": true,\n    \"conditions\": [\n      { \"rule_option\": { \"id\": 3, \"label\": \"branch\" }, \"operator\": \"in\", \"operand\": \"mastercard\" },\n      { \"rule_option\": { \"id\": 5, \"label\": \"currency\" }, \"operator\": \"in\", \"operand\": \"MXN\" }\n    ],\n    \"members\": [\n      { \"sort\": 1, \"strategy\": \"cascade\", \"fraud_provider\": \"CYBERSOURCE\" }\n    ],\n    \"children\": [\n      { \"conditions\": [ { \"rule_option\": { \"id\": 15 }, \"operator\": \"eq\", \"operand\": \"high\" } ], \"members\": [] },\n      { \"conditions\": [ { \"rule_option\": { \"id\": 15 }, \"operator\": \"eq\", \"operand\": \"medium\" } ],\n        \"members\": [ { \"sort\": 1, \"strategy\": \"cascade\", \"payment_provider_id\": 45, \"merchant_payment_provider_id\": \"6e4c651a-3e5f-403d-af9d-6a9e9299acb8\", \"capabilities\": [\"3ds\"], \"enabled3ds\": false } ] },\n      { \"conditions\": [ { \"rule_option\": { \"id\": 15 }, \"operator\": \"eq\", \"operand\": \"low\" } ],\n        \"members\": [ { \"sort\": 1, \"strategy\": \"cascade\", \"payment_provider_id\": 45, \"merchant_payment_provider_id\": \"6e4c651a-3e5f-403d-af9d-6a9e9299acb8\", \"capabilities\": [\"3ds\"], \"enabled3ds\": false } ] }\n    ]\n  }"))
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

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

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Risposta `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}

Restituisce una singola regola, inclusa la sua conditions, members e qualsiasi children. rule_id è l'identificatore numerico.

cURL

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

const response = await fetch("https://api.sandbox.deuna.io/routing/v1/rules/21866", {
  method: "GET",
  headers: {
    "X-Api-Key": "{{API KEY}}"
  }
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "GET",
    "https://api.sandbox.deuna.io/routing/v1/rules/21866",
    headers={
        "X-Api-Key": "{{API KEY}}"
    },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/routing/v1/rules/21866",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: {{API KEY}}"
  ]
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sandbox.deuna.io/routing/v1/rules/21866"))
      .header("X-Api-Key", "{{API KEY}}")
      .method("GET", HttpRequest.BodyPublishers.noBody())
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  request, err := http.NewRequest("GET", "https://api.sandbox.deuna.io/routing/v1/rules/21866", nil)
  if err != nil { panic(err) }
  request.Header.Set("X-Api-Key", "{{API KEY}}")

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Risposta `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
    }
  ]
}

Errori: PAYROU-NOT_FOUND (404) se la regola non esiste; PAYROU-FORBIDDEN (403) se non è accesibile; PAYROU-INVALID_PATH_PARAM (400) se rule_id non è un intero valido.

Regole di elenco#

GET /routing/v1/rules

Restituisce regole per il vostro commerciante in ordine prioritario. I risultati sono impaginato con un cursore opaco.

Param di query	Tipo	Descrizione
`limit`	integer	Facoltativo. Dimensioni pagina. Predefinito `50`, massimo `200`.
`cursor`	string	Facoltativo. cursore Opaque da una risposta precedente `pagination.next_cursor`. Omit per la prima pagina.
`payment_provider_id`	integer	Facoltativo. Restituzione regole che fanno riferimento a questo fornitore di pagamento.

La risposta avvolge le regole in un pagination oggetto. Continua a chiedere con next_cursor mentre has_more è true.

`pagination` campo	Tipo	Descrizione
`next_cursor`	stringa \| null	Cursore per la pagina successiva, o `null` nell'ultima pagina.
`has_more`	boolean	`true` se sono disponibili più regole.
`limit`	integer	La dimensione della pagina che è stata applicata.

cURL

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

const response = await fetch("https://api.sandbox.deuna.io/routing/v1/rules?limit=50", {
  method: "GET",
  headers: {
    "X-Api-Key": "{{API KEY}}"
  }
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "GET",
    "https://api.sandbox.deuna.io/routing/v1/rules?limit=50",
    headers={
        "X-Api-Key": "{{API KEY}}"
    },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/routing/v1/rules?limit=50",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: {{API KEY}}"
  ]
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sandbox.deuna.io/routing/v1/rules?limit=50"))
      .header("X-Api-Key", "{{API KEY}}")
      .method("GET", HttpRequest.BodyPublishers.noBody())
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  request, err := http.NewRequest("GET", "https://api.sandbox.deuna.io/routing/v1/rules?limit=50", nil)
  if err != nil { panic(err) }
  request.Header.Set("X-Api-Key", "{{API KEY}}")

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Risposta `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"
    }
  ]
}

Aggiornare una regola#

PUT /routing/v1/rules/{rule_id}

Sostituto completo della regola. Inviare il corpo regola completo — la stessa forma di creare — compreso id e created_at. Uso comune: flip status tra enabled e disabled (questo è il modo in cui "ritire" una regola invece di eliminare).

cURL — disabilitare una regola

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 }
    ]
  }'

const response = await fetch("https://api.sandbox.deuna.io/routing/v1/rules/21866", {
  method: "PUT",
  headers: {
    "X-Api-Key": "{{API KEY}}",
    "X-Idempotency-Key": "7c2e5a19-4b8d-4f10-9a3c-1d2e3f4a5b6c",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "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
      }
    ]
  })
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "PUT",
    "https://api.sandbox.deuna.io/routing/v1/rules/21866",
    headers={
        "X-Api-Key": "{{API KEY}}",
        "X-Idempotency-Key": "7c2e5a19-4b8d-4f10-9a3c-1d2e3f4a5b6c",
        "Content-Type": "application/json"
    },
    json={
          "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
            }
          ]
        },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/routing/v1/rules/21866",
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: {{API KEY}}",
    "X-Idempotency-Key: 7c2e5a19-4b8d-4f10-9a3c-1d2e3f4a5b6c",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
      "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
        ]
      ]
    ])
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sandbox.deuna.io/routing/v1/rules/21866"))
      .header("X-Api-Key", "{{API KEY}}")
      .header("X-Idempotency-Key", "7c2e5a19-4b8d-4f10-9a3c-1d2e3f4a5b6c")
      .header("Content-Type", "application/json")
      .method("PUT", HttpRequest.BodyPublishers.ofString("{\n    \"id\": 21866,\n    \"created_at\": \"2026-07-08T01:07:29.439794Z\",\n    \"label\": \"MX Mastercard — Cybersource\",\n    \"priority\": 2,\n    \"status\": \"disabled\",\n    \"trigger\": \"merchant_rule\",\n    \"is_default\": false,\n    \"data_type\": \"credit_card\",\n    \"ignore_next_rules\": true,\n    \"conditions\": [\n      { \"id\": 44264, \"rule_option\": { \"id\": 3, \"label\": \"branch\" }, \"operator\": \"in\", \"operand\": \"mastercard\", \"operand_type\": \"values\" },\n      { \"id\": 44265, \"rule_option\": { \"id\": 5, \"label\": \"currency\" }, \"operator\": \"in\", \"operand\": \"MXN\", \"operand_type\": \"values\" }\n    ],\n    \"members\": [\n      { \"sort\": 1, \"strategy\": \"cascade\", \"fraud_provider\": \"CYBERSOURCE\", \"capabilities\": [], \"post_authorization\": false, \"shadow_mode\": false }\n    ]\n  }"))
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

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

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Risposta `200`

Restituisce la regola aggiornata con status Ora disabled. Nota: stato ids sono ristampati su aggiornamento.

Cambiare la priorità di una regola (riordine)#

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

Sposta una regola in una nuova priorità. Altre regole sono ri-sequenziate di conseguenza.

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 }'

const response = await fetch("https://api.sandbox.deuna.io/routing/v1/rules/21873/reorder", {
  method: "PUT",
  headers: {
    "X-Api-Key": "sk_sandbox_9f8b2c1a7d4e60b3",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "priority": 2
  })
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "PUT",
    "https://api.sandbox.deuna.io/routing/v1/rules/21873/reorder",
    headers={
        "X-Api-Key": "sk_sandbox_9f8b2c1a7d4e60b3",
        "Content-Type": "application/json"
    },
    json={
          "priority": 2
        },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/routing/v1/rules/21873/reorder",
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: sk_sandbox_9f8b2c1a7d4e60b3",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
      "priority" => 2
    ])
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sandbox.deuna.io/routing/v1/rules/21873/reorder"))
      .header("X-Api-Key", "sk_sandbox_9f8b2c1a7d4e60b3")
      .header("Content-Type", "application/json")
      .method("PUT", HttpRequest.BodyPublishers.ofString("{ \"priority\": 2 }"))
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  request, err := http.NewRequest("PUT", "https://api.sandbox.deuna.io/routing/v1/rules/21873/reorder", strings.NewReader("{ \"priority\": 2 }"))
  if err != nil { panic(err) }
  request.Header.Set("X-Api-Key", "sk_sandbox_9f8b2c1a7d4e60b3")
  request.Header.Set("Content-Type", "application/json")

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Campo	Tipo	Obbligatorio	Constraente
`priority`	integer	Sì.	`Non-negative integer`

Risposta `200`

JSON

{ "priority": 2 }

Errori: PAYROU-VALIDATION (400) con errors[].code = PRIORITY_OUT_OF_RANGE se priority non è un intero non negativo.

Validazioni#

Creare e aggiornare eseguire questi controlli. Qualsiasi errore restituisce HTTP 400 con il codice di alto livello PAYROU-VALIDATION e una voce per campo offensivo in errors[] (v. Errori per la busta e il catalogo completo di codice a livello di campo).

Livello di regola

status deve essere uno di enabled, disabled, draft, process-in-background.
trigger deve essere uno di payment, reject, merchant_rule.
trigger = payment → almeno un membro; nessun bambino.
trigger = reject → nessun membro, nessun bambino, ignore_next_rules deve essere falso, is_default deve essere falso.
trigger = merchant_rule → almeno un membro o almeno un bambino.
is_default = true → nessuna condizione e ignore_next_rules deve essere falso.
is_default = false → almeno una condizione.
priority deve essere > 0 e ≤ 1000.

Condizioni

rule_option.id richiesto (> 0); operand richiesto (non-vuoto).
operator deve essere valido per quella opzione di regola (vedi catalogo).
A rule_option può apparire solo una volta per regola (escluso metadata).
per metadata (id 16): metadata_field_name e metadata_field_type richiesto; il tipo deve essere text o numeric.
per operand_type = list: operand deve essere una lista valida UUID che esiste.

Membri

Ogni membro deve fare riferimento esattamente ad un tipo di fornitore: pagamento, pagamento commerciante, frode o autenticazione.
I tipi di fornitori non possono essere mescolati su un membro.
Se merchant_payment_provider_id è presente, payment_provider_id deve essere presente anche.
I membri dell'autenticazione richiedono authentication_type (uno di 3ds_authentication, 3ds_data_only, unico_id).
failover è valido solo solo sui membri dell'autenticazione; i suoi authentication_type deve essere anche un valore valido.
sort deve essere unico all'interno della regola.
Un fornitore può apparire solo una volta per regola.
strategy deve essere cascade.
post_authorization = true solo per i fornitori di frodi, e quel membro deve essere Ultimo ultimo di sort.

Livello di servizio (controllato contro la configurazione del commerciante)

L'opzione di regola di riferimento deve esistere e sostenere l'operatore dato.
Il fornitore di pagamento/pagamento/frode/autenticazione deve essere abilitato per il commerciante.
merchant_payment_provider_id deve appartenere al dato payment_provider_id.

Errori#

Busta di errore

Ogni risposta di errore utilizza la stessa forma 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'."
    }
  ]
}

Campo	Tipo	Descrizione
`code`	string	Codice di alto livello stabile e leggibile dalla macchina. Branch su questo, mai on `message`.
`message`	string	Riepilogo leggibile dall'uomo. Può essere riparlato o localizzato — non lo parse.
`request_id`	string	Unico per risposta e anche tornato nel `X-Request-Id` intestazione di risposta (su successo e errore). Citarlo in qualsiasi richiesta di supporto.
`errors`	array	Presente solo per `PAYROU-VALIDATION`. Una voce per campo offensivo.
`errors[].field`	string	Percorso sul campo, utilizzando notazione punti/freschetti — ad esempio. `priority`, `conditions[1].operand`, `members[0].sort`.
`errors[].code`	string	Codice di livello del campo stabile (vedere codici di convalida).
`errors[].message`	string	Dettaglio leggibile dall'uomo. Non fare la parsa.

Invia sempre un messaggio X-Idempotency-Key su scritture. Riprodurre la stessa chiave restituisce la risposta originale; riutilizzare una chiave con una diverso ritorno del corpo 409 PAYROU-CONFLICT.

Codici di stato HTTP

Stato	Significato
`200` / `201`	Success.
`400`	La richiesta è invalida — la convalida non è riuscita, malformata JSON, o i param difettosi di percorso/query.
`401`	Autenticazione fallita — `X-Api-Key` manca o non è valido.
`403`	Autorizzazione fallito — la chiave è valida ma non è consentito accedere a questo commerciante / risorse.
`404`	La regola o una risorsa di riferimento non esiste.
`409`	Conflitto — il riutilizzo chiave di idempotency con un corpo diverso, o un aggiornamento concomitante.
`429`	Limite di tasso superiore — riprovazione dopo `Retry-After` header.
`500`	Errore del server inaspettato.
`503`	Una dipendenza a valle è temporaneamente non disponibile — sicuro da riprovare con il backoff.

Codici di livello superiore

Codice	HTTP	Quando
`PAYROU-VALIDATION`	400	Uno o più campi non sono riusciti a convalidare. Dettagli in `errors[]`.
`PAYROU-MALFORMED_JSON`	400	Il corpo di richiesta non è valido JSON.
`PAYROU-INVALID_PATH_PARAM`	400	Un parametro del percorso è il tipo/formato sbagliato (ad esempio non integer) `rule_id`).
`PAYROU-INVALID_QUERY_PARAM`	400	Un parametro di query è non valido (ad es. `limit` fuori portata, malformato `cursor`).
`PAYROU-UNAUTHENTICATED`	401	Mancante o non valida chiave API.
`PAYROU-FORBIDDEN`	403	Chiave valida, ma non portata a questo commerciante / risorse.
`PAYROU-NOT_FOUND`	404	Regola o risorsa di riferimento non trovata.
`PAYROU-CONFLICT`	409	Riutilizzo chiave di Idempotency con un carico di pagamento diverso, o modifica concomitante.
`PAYROU-RATE_LIMITED`	429	Troppe richieste.
`PAYROU-INTERNAL`	500	Errore del server inaspettato.
`PAYROU-UPSTREAM_UNAVAILABLE`	503	Una dipendenza a valle non è temporaneamente disponibile.

Codici di convalida

Ritornato dentro errors[] quando il codice di primo livello è PAYROU-VALIDATION. Ognuno è stabile e sicuro da ramificarsi.

Livello di regola

`code`	Tipico `field`	Causa
`INVALID_STATUS`	`status`	Non uno di `enabled`, `disabled`, `draft`, `process-in-background`.
`INVALID_TRIGGER`	`trigger`	Non uno di `payment`, `reject`, `merchant_rule`.
`PRIORITY_OUT_OF_RANGE`	`priority`	Non trascurabile `1` e `1000` (coperte entrambe) `≤ 0` e `> 1000`).
`MEMBERS_REQUIRED`	`members`	`trigger = payment` senza membri.
`MEMBERS_OR_CHILDREN_REQUIRED`	`members`	`trigger = merchant_rule` con né membri né figli.
`CONDITIONS_REQUIRED`	`conditions`	Regola non di default senza condizioni.
`TRIGGER_CANNOT_BE_DEFAULT`	`is_default`	`reject` regola con `is_default = true`.
`TRIGGER_CANNOT_HAVE_MEMBERS`	`members`	`reject` governare con i membri.
`TRIGGER_CANNOT_HAVE_CHILDREN`	`children`	`payment`/`reject` governare con i bambini.
`TRIGGER_CANNOT_IGNORE_NEXT_RULES`	`ignore_next_rules`	`reject` regola con `ignore_next_rules = true`.
`DEFAULT_RULE_CANNOT_HAVE_CONDITIONS`	`conditions`	Regola di default con le condizioni.
`DEFAULT_RULE_CANNOT_IGNORE_NEXT_RULES`	`ignore_next_rules`	Regola di default con `ignore_next_rules = true`.

Condizioni

`code`	Tipico `field`	Causa
`RULE_OPTION_ID_REQUIRED`	`conditions[i].rule_option.id`	Mancato o `≤ 0`.
`OPERAND_REQUIRED`	`conditions[i].operand`	Operando vuoto per un operatore che ne richiede uno.
`OPERATOR_REQUIRED`	`conditions[i].operator`	L'operatore è vuoto.
`INVALID_OPERATOR`	`conditions[i].operator`	Operatore non valido per tale opzione di regola.
`DUPLICATE_RULE_OPTION`	`conditions[i].rule_option`	Stessa opzione di regola utilizzata più di una volta (escluso `metadata`).
`METADATA_FIELDS_REQUIRED`	`conditions[i].metadata_field_name`	`metadata` condizione mancante `metadata_field_name`/`metadata_field_type`.
`INVALID_METADATA_FIELD_TYPE`	`conditions[i].metadata_field_type`	Non lo so. `text` o `numeric`.
`RULE_OPTION_NOT_FOUND`	`conditions[i].rule_option.id`	L'opzione di regola non esiste.
`INVALID_LIST_REFERENCE`	`conditions[i].operand`	`operand_type = list` ma la lista UUID è non valida o non trovata.

Membri

`code`	Tipico `field`	Causa
`MEMBER_PROVIDER_REQUIRED`	`members[i]`	I membri non fanno riferimento a provider (pagamento, frode o autenticazione).
`MEMBER_MULTIPLE_PROVIDER_TYPES`	`members[i]`	I membri mescolano i tipi di fornitori (ad esempio il pagamento + frode, o il pagamento + autenticazione).
`PAYMENT_PROVIDER_ID_REQUIRED`	`members[i].payment_provider_id`	`merchant_payment_provider_id` inviato senza `payment_provider_id`.
`AUTHENTICATION_TYPE_REQUIRED`	`members[i].authentication_type`	Membro di autenticazione senza un `authentication_type`.
`INVALID_AUTHENTICATION_TYPE`	`members[i].authentication_type`	Non uno di `3ds_authentication`, `3ds_data_only`, `unico_id` (Applicazioni) `failover.authentication_type` anche).
`FAILOVER_ONLY_ON_AUTHENTICATION`	`members[i].failover`	`failover` su un membro non-autentico.
`DUPLICATE_MEMBER`	`members[i]`	Lo stesso fornitore appare più di una volta nella regola.
`DUPLICATE_MEMBER_SORT`	`members[i].sort`	Due membri condividono una `sort` value.
`INVALID_STRATEGY`	`members[i].strategy`	Non lo so. `cascade`.
`POST_AUTH_ONLY_FRAUD`	`members[i].post_authorization`	`post_authorization = true` su un membro non-fraud.
`POST_AUTH_MUST_BE_LAST`	`members[i].post_authorization`	Il `post_authorization` membro non è ultimo da `sort`.
`PROVIDER_NOT_AVAILABLE`	`members[i]`	Il Fornitore (pagamento, frode o autenticazione) non è abilitato per questo commerciante.
`MERCHANT_PROVIDER_MISMATCH`	`members[i].merchant_payment_provider_id`	La connessione non appartiene alla data `payment_provider_id`.

Test A/B

`code`	Tipico `field`	Causa
`SPLIT_WEIGHTS_MUST_SUM_TO_100`	`children`	Bambino bambino `weight` i valori non sommano a `100`.

Flusso end-to-end#

Il /triggers Supporti endpoint due modalità di integrazione — scegliere quale sia la quantità della logica di decisione che si desidera possedere. Entrambi usano lo stesso punto finale e le stesse regole; solo la forma di risposta e il numero di chiamate differiscono. Selezionalo con mode su richiesta (single è il default). In entrambi i casi, chiudi il loop con uno /feedback call.

Modalità	Come funziona	Quando è meglio
1 · Singola chiamata (Client-driven)	Uno `/triggers` chiamata restituisce il piano completo — l'autenticazione da eseguire (con failover) e `actions` che mappano ogni risultato a processo o declino. Eserciti il piano da solo.	Vuoi le ultime gite e sei comodo ad applicare la decisione a livello locale.
2 · Guidato (motore-driven)	Chiamate `/triggers` e il motore ritorna solo il passo successivo più un `status`. Lo esegua, poi chiama `/triggers` di nuovo con il risultato di quel passo; il motore restituisce il passo successivo. Ripeti fino a quando non `status = completed`.	Vuoi che DEUNA possieda e centralizzi la logica decisionale, passo dopo passo.

Modalità 1 — singola chiamata

Tu fai singolo /triggers Chiama. Se si esegue un fornitore di frode prima di DEUNA, includere il suo risultato in quella chiamata. La risposta è autocontenuta: si nomina l'autenticazione da eseguire (con un fallire se il primario non è disponibile) e il azioni che mappa il risultato di autenticazione a cosa fare successivo — processo con un fornitore di pagamento o declino. La tua piattaforma esegue che pianifica localmente e chiude il loop con uno /feedback — c'è un no second /triggers round-trip.

Passo dopo passo

(Opzionale) Punteggio con un fornitore di frode. Se la configurazione utilizza un provider di frode in alto, cattura il suo punteggio / decisione in modo che possa essere abbinato alle regole (tramite le regole) fraud_risk opzione o metadata).
Richiedere la raccomandazione (una chiamata). POST /routing/v1/triggers con i dati delle transazioni (e il risultato delle frodi, se ne ha). La risposta contiene un authentication blocco (primary + facoltativo failover) e actions block.
Authenticate. Eseguire l'autenticazione raccomandata (ad esempio autenticazione 3DS, solo dati 3DS, o ID Unico). Se il primary il fornitore non è disponibile, utilizzare failover.
Decide e processa. Applicare actions: ogni esito mappa a process (con il fornitore di pagamento denominato nell'azione) o decline; default l'azione si applica quando nessun altro risultato corrisponde.
Segnala il risultato. POST /routing/v1/feedback con il collection oggetto e attempts (risultato di autenticità + risultato di pagamento). Questo chiude il loop per l'analisi e l'etichettatura ML.

I commercianti con un unico fornitore di pagamento vedranno un fornitore nel process azione; i commercianti con diversi possono configurare una cascata nella regola members, e la raccomandazione riflette il provider(i) di tentare.

Diagramma di sequenza

Commerciante o clienteProvider o processoreDEUNA

Risposta della modalità 1 — il piano completo

Il /triggers risposta è una raccomandazione unica e autonoma: authentication da eseguire (con opzione failover) e actions che mappa il risultato di autenticazione a cosa fare. La tua piattaforma esegue questo localmente.

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" }
    }
  }
}

Campo	Tipo	Descrizione
`collection.id`	UUID	ID di correlazione per questa valutazione. Echo in `/feedback`.
`collection.prediction_id`	string	ML maniglia per la raccomandazione. Echo in `/feedback`.
`recommendation.rule_id`	integer	La regola che corrispondeva (stesso identificativo come l'oggetto di regola) `id`).
`recommendation.rule_label`	string	Nome di regola leggibile dall'uomo.
`recommendation.authentication.primary`	object	L'autenticazione da eseguire prima: `{ "authentication_type": "3ds_authentication" }`. Utilizza lo stesso `authentication_type` valori come membri della regola.
`recommendation.authentication.failover`	oggetto \| null	Autenticazione di backup se il primario non è disponibile.
`recommendation.actions`	object	Consente di visualizzare il risultato dell'autenticazione in un'azione. Chiuso per risultato.
`recommendation.actions.<outcome>.action`	enumera	`process` o `decline`.
`recommendation.actions.<outcome>.provider`	string	Presente quando `action = process` — il nome del fornitore di pagamento da utilizzare, come configurato nella regola (ad es. `acquirer_gateway`).
`recommendation.actions.default`	object	L'azione di fallback applicata quando nessun altro risultato corrisponde.

Tasti di uscita sotto actions descrivere il risultato di autenticazione a cui si applicano (ad es. on_success_with_liability_shift); default è il catch-all.

Modalità 2 — guidati (passo)

Imposta "mode": "guided" su richiesta. Invece del piano completo, il motore restituisce il passo successivo e un status, e si guida il flusso un passo alla volta:

status: awaiting_authentication → next_step ti dice quale autenticazione eseguire.
status: awaiting_fraud → next_step ti dice quale controllo frode per eseguire.
status: completed → il motore ha deciso; next_step.action è process (con un provider) o decline.

Dopo aver eseguito un passo, chiama /triggers — di nuovo — eco il collection dalla risposta precedente e includere il risultato di quel passaggio (authentication_result o fraud_result). Il motore avanza e ritorna il passo successivo. Ripeti fino a quando non status = completed, poi vicino con /feedback.

Diagramma di sequenza

Commerciante o clienteDEUNA

Prima risposta — un passo per eseguire

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" }
    }
  }
}

Richiesta di follow-up — posta il risultato del passaggio

JSON

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

Risposta del terminale — 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" }
  }
}

Campo	Tipo	Descrizione
`mode`	enumera	Campo di richiesta: `single` (predefinito) o `guided`.
`collection`	object	Campo richiesta su chiamate guidate di follow-up: eco il `collection` dalla risposta precedente per continuare la stessa valutazione.
`authentication_result` / `fraud_result`	object	Campo richiesta: il risultato del passaggio appena eseguito.
`recommendation.status`	enumera	`awaiting_authentication`, `awaiting_fraud`o `completed`.
`recommendation.next_step.type`	enumera	`authentication`, `fraud`, `process`o `decline`.
`recommendation.next_step.authentication_type`	enumera	Presente quando `type = authentication`.
`recommendation.next_step.failover`	oggetto \| null	Backup opzionale per una fase di autenticazione.
`recommendation.next_step.provider`	string	Presente quando `type = process` — il fornitore di pagamento da utilizzare.

Entrambe le modalità sono sostenute dalle stesse regole e producono le stesse decisioni — la modalità guidata chiede semplicemente a DEUNA per un passo alla volta invece di restituire l'intero piano davanti.

Identificazione della carta su `/triggers`

La carta in payment_source.card_info può essere fornito uno dei tre modi:

Metodo	Campi	Note
PAN completa	`card_number`	BIN e marca sono derivate lato server.
BIN + ultimi quattro	`bin` (8 cifre), `last_four`	Usa quando non si trasmette il PAN completo. Il BIN a 8 cifre dà un routing di livello emittente.
Token di rete	`network_token`: `{ dpan, par, account_bin, cryptogram, eci }`	Per le credenziali tokenizzate. Vedere la nota qui sotto per ottenere i dati di livello BIN.

Feedback `attempts` esempio

attempts segnala cosa è successo: il risultato dell'autenticazione, quindi il risultato del pagamento dal tuo fornitore di pagamento (codici 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 utilizza i codici di risposta ISO 8583 — ad esempio. "05" = non onorare. eci e pares_status portare il risultato 3DS; liability_shift indica se l'autenticazione ha spostato la responsabilità.

Autenticazione di backup (failover)

Le regole possono definire fallire provider di autenticazione. Se il raccomandato primary provider non è disponibile (ad esempio il fornitore di autenticazione 3DS è in calo), la raccomandazione restituisce failover (ad esempio 3DS Data Only) quindi un'interruzione del fornitore non lascia mai una transazione non autenticata.

Domande o dettagli mancanti? Contatta il tuo team di integrazione DEUNA.