Mecanismo de recomendação

Defina a rota ordenada de provedores avaliada para uma regra correspondente.

Acme LATAM · Produção

ConfiguraçãoMecanismo de recomendação

Ativa

01AdyenRota principal

02WorldpayRota alternativa

03StripeRota alternativa

RoteamentoAdyen → Worldpay → Stripe

Autenticação#

Todos os endpoints são autenticados com um Chave de API enviado no X-Api-Key header — este é o único esquema de autenticação suportado. Seu comerciante foi resolvido a partir da chave API, então o identificador do comerciante faz não aparecem no URL.

HTTP

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

Cabeçalho	Obrigatório	Descrição
`X-Api-Key`	Sim	Sua chave de API. Determina o ambiente e o escopo do comerciante.
`Content-Type`	Sim	`application/json`.
`X-Idempotency-Key`	Recomendado	Uma chave exclusiva gerada por solicitação lógica (um UUID funciona bem). Tentar novamente com a mesma chave retorna o resultado original em vez de aplicar a operação duas vezes – envie-a para que as tentativas de rede nunca criem regras duplicadas ou contem duas vezes uma ação.

Resumo do endpoint#

Método	Caminho	Objetivo
`GET`	`/routing/v1/rules`	Liste todas as regras (ordem de prioridade)
`POST`	`/routing/v1/rules`	Crie uma regra
`GET`	`/routing/v1/rules/{rule_id}`	Get a single rule by ID
`PUT`	`/routing/v1/rules/{rule_id}`	Atualizar uma regra (substituição completa)
`PUT`	`/routing/v1/rules/{rule_id}/reorder`	Alterar a prioridade de uma regra

Parâmetros do caminho:

Parâmetro	Tipo	Notas
`rule_id`	integer	Identificador de regra numérico retornado por create/list.

O objeto Regra#

Uma regra é o recurso principal retornado e aceito por esses terminais.

Campo	Tipo	Obrigatório	Descrição
`id`	integer	Apenas resposta	Identificador de regra atribuído pelo servidor.
`label`	string	Sim	Nome da regra legível por humanos.
`data_type`	string	Sim	Família de métodos à qual esta regra se aplica: `credit_card`, `debit_card`, `prepaid_card`.
`priority`	integer	Sim	Ordem de avaliação — corridas mais baixas primeiro, a primeira partida vence (números não negativos)
`status`	enumeração	Sim	`enabled`, `disabled`, `draft`
`is_default`	boolean	Sim	Se `true`, esta é a regra alternativa quando nenhuma outra correspondência. Uma regra padrão deve ter não condições e não deve definir `ignore_next_rules`.
`trigger`	enumeração	Sim	`payment`, `reject`, ou `merchant_rule`. Consulte Gatilhos.
`conditions`	array<Condition>	Condicional	Critérios de correspondência, E-combinado. Obrigatório, a menos que `is_default = true`.
`members`	array<Member>	Condicional	Provedores ordenados a tentar. Obrigatório para `payment`; necessário (ou `children`) para `merchant_rule`; proibido para `reject`.
`children`	array<Child>	Opcional	Branches filhos ponderados para testes A/B (somente com `trigger = merchant_rule`).
`ignore_next_rules`	boolean	Sim	Se `true`, pare de avaliar outras regras quando esta corresponder. Proibido para `reject` e para regras padrão.
`created_at`	cadeia de caracteres (RFC3339)	Apenas resposta	Carimbo de data e hora de criação.

Gatilhos

`trigger`	Significado	`members`	`children`	`ignore_next_rules`	`is_default`
`payment`	Encaminhe o pagamento para os provedores listados.	Obrigatório (≥1)	Não permitido	Permitido	Permitido
`reject`	Bloqueie a transação imediatamente.	Não permitido	Não permitido	Não permitido	Não permitido
`merchant_rule`	Grupo/filial: rota através de membros ou crianças pesadas.	Obrigatório se não houver filhos	Permitido	Permitido	Permitido

O objeto Condição#

As condições definem o que uma transação deve corresponder. Todas as condições de uma regra são combinadas com AND.

Campo	Tipo	Obrigatório	Descrição
`id`	integer	Apenas resposta	ID de condição atribuída pelo servidor.
`rule_option`	object	Sim	O campo a ser correspondido, por exemplo `{ "id": 5, "label": "currency" }`. Utilize uma opção de regra disponível para o lojista; `id` deve ser `> 0`.
`operator`	enumeração	Sim	Operador de comparação. Deve ser válido para essa opção de regra
`operand`	string	Condicional	O(s) valor(es) para comparar, sempre serializado como uma string. O formato depende da operadora. Obrigatório para cada operador exceto `is_present`, que não aceita operando.
`operand_type`	string	Não	`values` (padrão) ou `list` (o operando faz referência a uma lista personalizada por UUID).
`operand_config`	objeto \| nulo	Condicional	Usado quando `operand_type = list`: `{ "custom_list": { "field_to_evaluate": "email" } }`.
`metadata_field_name`	cadeia \| nulo	Condicional	Obrigatório quando `rule_option.id = 16` (`metadata`). A chave de metadados a ser avaliada.
`metadata_field_type`	cadeia \| nulo	Condicional	Obrigatório quando `rule_option.id = 16`. Um dos `text`, `numeric`.
`error_code`	string	Apenas resposta	Definido quando o processamento assíncrono de uma condição (por exemplo, importação de lista) falhou.
`error_message`	string	Apenas resposta	Detalhes legíveis por humanos para `error_code`.

Exemplo – combinar cartões da marca Mastercard

JSON

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

O objeto Membro#

Os membros são os provedores que uma regra correspondente usa, tentada em sort ordem (a cascata). Um membro faz referência um provedor - um provedor de pagamento, um provedor de fraude, ou um provedor de autenticação.

Campo	Tipo	Obrigatório	Descrição
`payment_provider_id`	integer	Condicional	ID do provedor de pagamento DEUNA. Obrigatório se `merchant_payment_provider_id` está presente.
`payment_provider_name`	string	Apenas resposta	Nome do provedor (ecoado de volta).
`merchant_payment_provider_id`	UUID	Condicional	Conexão de provedor específica do comerciante. Se enviado, `payment_provider_id` deve também será enviado.
`merchant_payment_provider_name`	string	Apenas resposta	Nome da conexão (ecoado de volta).
`fraud_provider`	string	Condicional	Nome do provedor antifraude/fraude. Mutuamente exclusivos com campos de provedor de pagamento e autenticação.
`fraud_provider_id`	string	Apenas resposta	ID do provedor de fraude (repetido).
`authentication_provider`	string	Condicional	Nome do provedor de autenticação (por exemplo `UNICO_ID`, `CYBERSOURCE_3DS`). Mutuamente exclusivo com campos de provedor de pagamento e fraude.
`authentication_provider_id`	string	Apenas resposta	ID do provedor de autenticação (ecoado de volta).
`authentication_type`	enumeração	Condicional	O método de autenticação. Um dos `3ds_authentication`, `3ds_data_only`, `unico_id`. Obrigatório quando o membro é um provedor de autenticação.
`failover`	objeto \| nulo	Opcional	Autenticação de backup usada quando o provedor principal não está disponível: `{ "authentication_provider": "...", "authentication_type": "..." }`. Válido apenas em membros do provedor de autenticação.
`sort`	integer	Sim	Ordem em cascata. Deve ser único dentro da regra.
`strategy`	enumeração	Sim	Atualmente apenas `cascade`.
`capabilities`	array<string>	Sim	Capacidades do provedor para usar, por ex. `["3ds"]`. Enviar `[]` se nenhum.
`enabled3ds`	boolean	Não	Solicite autenticação 3DS neste membro (crie carga útil).
`post_authorization`	boolean	Sim	Apenas um fraude provedor pode definir `true`, e deve ser o último membro por `sort`.
`shadow_mode`	boolean	Sim	Avalie o provedor sem afetar a rota (teste seguro).
`enabled`	boolean	Apenas resposta	Se o provedor está atualmente disponível para o comerciante.

Exemplo – membro do provedor de 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
}

Exemplo – membro provedor de fraude

JSON

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

Exemplo — membro do provedor de autenticação (com 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
}

Teste A/B – divida o tráfego entre duas rotas#

Para o teste A/B, adicione dois rotas a uma regra (como children) e dê a cada um uma porcentagem weight. O mecanismo envia essa parcela de transações correspondentes para cada rota — por exemplo, 70% para a Rota A, 30% para a Rota B – para que você possa compará-los no tráfego ao vivo.

Campo	Tipo	Obrigatório	Descrição
`weight`	integer	Sim	Porcentagem de tráfego correspondente enviado para esta rota. Os pesos das duas rotas devem somar `100`.
`members`	array<Member>	Sim	O(s) provedor(es) para esta rota.

Regras:

Exatamente dois routes.
weight os valores devem somar 100.
A regra deve ser definida ignore_next_rules: true.
A tarefa é pegajoso por transaction_id (uma transação sempre obtém a mesma rota), e a rota executada é ecoada de volta no /triggers response.

Exemplo – divisão 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" }
      ]
    }
  ]
}

Crie uma regra#

POST /routing/v1/rules

O exemplo abaixo cria um merchant_rule para cartões de crédito Mastercard em MXN, executa uma verificação de fraude e depois ramifica por fraud_risk: bloquear highe rota medium/low para 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))
}

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

Retorna uma única regra, incluindo seu conditions, members e qualquer children. rule_id é o identificador numérico.

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

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

Erros: PAYROU-NOT_FOUND (404) se a regra não existir; PAYROU-FORBIDDEN (403) se não estiver acessível; PAYROU-INVALID_PATH_PARAM (400) se rule_id não é um número inteiro válido.

Listar regras#

GET /routing/v1/rules

Regras de devolução para seu comerciante em ordem de prioridade. Os resultados são paginado com um cursor opaco.

Parâmetro de consulta	Tipo	Descrição
`limit`	integer	Opcional. Tamanho da página. Padrão `50`, máximo `200`.
`cursor`	string	Opcional. Cursor opaco de uma resposta anterior `pagination.next_cursor`. Omitir na primeira página.
`payment_provider_id`	integer	Opcional. Retorne apenas regras que façam referência a esse provedor de pagamento.

A resposta envolve as regras em um pagination objeto. Continue solicitando com next_cursor enquanto has_more é true.

`pagination` campo	Tipo	Descrição
`next_cursor`	cadeia \| nulo	Cursor para a próxima página ou `null` na última página.
`has_more`	boolean	`true` se mais regras estiverem disponíveis.
`limit`	integer	O tamanho da página que foi aplicado.

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

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

Atualizar uma regra#

PUT /routing/v1/rules/{rule_id}

Substituição completa da regra. Envie o corpo completo da regra — a mesma forma que criar — incluindo id e created_at. Uso comum: virar status entre enabled e disabled (é assim que você "retira" uma regra em vez de excluí-la).

cURL — desabilitando uma regra

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

Resposta `200`

Retorna a regra atualizada com status agora disabled. Nota: condição ids são reemitidos na atualização.

Alterar a prioridade de uma regra (reordenar)#

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

Move uma regra para uma nova prioridade. Outras regras são sequenciadas novamente de acordo.

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	Obrigatório	Restrição
`priority`	integer	Sim	`Non-negative integer`

Resposta `200`

JSON

{ "priority": 2 }

Erros: PAYROU-VALIDATION (400) com errors[].code = PRIORITY_OUT_OF_RANGE se priority não é um número inteiro não negativo.

Validações#

Crie e atualize, execute essas verificações. Qualquer falha retorna HTTP 400 com código de nível superior PAYROU-VALIDATION e uma entrada por campo incorreto em errors[] (veja Erros para o envelope e o catálogo completo de códigos em nível de campo).

Nível de regra

status deve ser um dos enabled, disabled, draft, process-in-background.
trigger deve ser um dos payment, reject, merchant_rule.
trigger = payment → pelo menos um membro; sem filhos.
trigger = reject → sem membros, sem filhos, ignore_next_rules deve ser falso, is_default deve ser falso.
trigger = merchant_rule → pelo menos um membro ou pelo menos um filho.
is_default = true → sem condições e ignore_next_rules deve ser falso.
is_default = false → pelo menos uma condição.
priority deve ser > 0 e ≤ 1000.

Condições

rule_option.id obrigatório (> 0); operand obrigatório (não vazio).
operator deve ser válido para essa opção de regra (ver catálogo).
Um rule_option pode aparecer apenas uma vez por regra (exceto metadata).
Para metadata (identificação 16): metadata_field_name e metadata_field_type obrigatório; tipo deve ser text ou numeric.
Para operand_type = list: operand deve ser um UUID de lista válido que exista.

Membros

Cada membro deve fazer referência a exatamente um tipo de provedor: pagamento, pagamento ao comerciante, fraude ou autenticação.
Os tipos de provedores não podem ser misturados em um membro.
Se merchant_payment_provider_id está presente, payment_provider_id também deve estar presente.
Os membros de autenticação exigem authentication_type (um dos 3ds_authentication, 3ds_data_only, unico_id).
failover é válido apenas em membros de autenticação; é authentication_type também deve ser um valor válido.
sort deve ser único dentro da regra.
Um provedor pode aparecer apenas uma vez por regra.
strategy deve ser cascade.
post_authorization = true apenas para provedores de fraude, e esse membro deve ser último por sort.

Nível de serviço (verificado em relação à configuração do comerciante)

A opção de regra referenciada deve existir e suportar o operador fornecido.
O provedor de pagamento/pagamento do comerciante/fraude/autenticação referenciado deve estar habilitado para o comerciante.
merchant_payment_provider_id deve pertencer ao dado payment_provider_id.

Erros#

Envelope de erro

Cada resposta de erro usa o mesmo formato 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	Descrição
`code`	string	Código de nível superior estável e legível por máquina. Ramo sobre isto, nunca no `message`.
`message`	string	Resumo legível por humanos. Pode ser reformulado ou localizado — não o analise.
`request_id`	string	Único por resposta e também retornado no `X-Request-Id` cabeçalho de resposta (em caso de sucesso e erro). Cite-o em qualquer solicitação de suporte.
`errors`	array	Presente apenas para `PAYROU-VALIDATION`. Uma entrada por campo incorreto.
`errors[].field`	string	Caminho para o campo, usando notação de ponto/colchete — por exemplo. `priority`, `conditions[1].operand`, `members[0].sort`.
`errors[].code`	string	Código estável em nível de campo (consulte códigos de validação).
`errors[].message`	string	Detalhe legível por humanos. Não analise.

Envie sempre um X-Idempotency-Key em gravações. A repetição da mesma chave retorna a resposta original; reutilizando uma chave com um diferente corpo retorna 409 PAYROU-CONFLICT.

Códigos de status HTTP

Estado	Significado
`200` / `201`	Success.
`400`	A solicitação é inválida — falha na validação, JSON malformado ou parâmetros de caminho/consulta incorretos.
`401`	Autenticação falhou - o `X-Api-Key` está faltando ou é inválido.
`403`	Autorização falhou — a chave é válida, mas não tem permissão para acessar este comerciante/recurso.
`404`	A regra ou um recurso referenciado não existe.
`409`	Conflito — reutilização da chave de idempotência com um corpo diferente ou uma atualização simultânea.
`429`	Limite de taxa excedido — tente novamente após o `Retry-After` header.
`500`	Erro inesperado do servidor.
`503`	Uma dependência downstream está temporariamente indisponível – é seguro tentar novamente com espera.

Códigos de nível superior

Código	HTTP	Quando
`PAYROU-VALIDATION`	400	Um ou mais campos falharam na validação. Detalhes em `errors[]`.
`PAYROU-MALFORMED_JSON`	400	O corpo da solicitação não é JSON válido.
`PAYROU-INVALID_PATH_PARAM`	400	Um parâmetro de caminho é do tipo/formato errado (por exemplo, não inteiro `rule_id`).
`PAYROU-INVALID_QUERY_PARAM`	400	Um parâmetro de consulta é inválido (por exemplo, `limit` fora de alcance, malformado `cursor`).
`PAYROU-UNAUTHENTICATED`	401	Chave de API ausente ou inválida.
`PAYROU-FORBIDDEN`	403	Chave válida, mas sem escopo para este comerciante/recurso.
`PAYROU-NOT_FOUND`	404	Regra ou recurso referenciado não encontrado.
`PAYROU-CONFLICT`	409	Reutilização de chave de idempotência com uma carga útil diferente ou modificação simultânea.
`PAYROU-RATE_LIMITED`	429	Muitos pedidos.
`PAYROU-INTERNAL`	500	Erro inesperado do servidor.
`PAYROU-UPSTREAM_UNAVAILABLE`	503	Uma dependência downstream está temporariamente indisponível.

Códigos de validação

Devolvido para dentro errors[] quando o código de nível superior é PAYROU-VALIDATION. Cada um é estável e seguro para ramificar.

Nível de regra

`code`	Típico `field`	Causa
`INVALID_STATUS`	`status`	Nenhum dos `enabled`, `disabled`, `draft`, `process-in-background`.
`INVALID_TRIGGER`	`trigger`	Nenhum dos `payment`, `reject`, `merchant_rule`.
`PRIORITY_OUT_OF_RANGE`	`priority`	Não entre `1` e `1000` (abrange ambos `≤ 0` e `> 1000`).
`MEMBERS_REQUIRED`	`members`	`trigger = payment` sem membros.
`MEMBERS_OR_CHILDREN_REQUIRED`	`members`	`trigger = merchant_rule` sem membros nem filhos.
`CONDITIONS_REQUIRED`	`conditions`	Regra não padrão sem condições.
`TRIGGER_CANNOT_BE_DEFAULT`	`is_default`	`reject` governar com `is_default = true`.
`TRIGGER_CANNOT_HAVE_MEMBERS`	`members`	`reject` governar com os membros.
`TRIGGER_CANNOT_HAVE_CHILDREN`	`children`	`payment`/`reject` governar com crianças.
`TRIGGER_CANNOT_IGNORE_NEXT_RULES`	`ignore_next_rules`	`reject` governar com `ignore_next_rules = true`.
`DEFAULT_RULE_CANNOT_HAVE_CONDITIONS`	`conditions`	Regra padrão com condições.
`DEFAULT_RULE_CANNOT_IGNORE_NEXT_RULES`	`ignore_next_rules`	Regra padrão com `ignore_next_rules = true`.

Condições

`code`	Típico `field`	Causa
`RULE_OPTION_ID_REQUIRED`	`conditions[i].rule_option.id`	Faltando ou `≤ 0`.
`OPERAND_REQUIRED`	`conditions[i].operand`	Operando vazio para um operador que requer um.
`OPERATOR_REQUIRED`	`conditions[i].operator`	O operador está vazio.
`INVALID_OPERATOR`	`conditions[i].operator`	Operador não válido para essa opção de regra.
`DUPLICATE_RULE_OPTION`	`conditions[i].rule_option`	A mesma opção de regra usada mais de uma vez (exceto `metadata`).
`METADATA_FIELDS_REQUIRED`	`conditions[i].metadata_field_name`	`metadata` condição ausente `metadata_field_name`/`metadata_field_type`.
`INVALID_METADATA_FIELD_TYPE`	`conditions[i].metadata_field_type`	Não `text` ou `numeric`.
`RULE_OPTION_NOT_FOUND`	`conditions[i].rule_option.id`	A opção de regra não existe.
`INVALID_LIST_REFERENCE`	`conditions[i].operand`	`operand_type = list` mas o UUID da lista é inválido ou não foi encontrado.

Membros

`code`	Típico `field`	Causa
`MEMBER_PROVIDER_REQUIRED`	`members[i]`	O membro não faz referência a nenhum provedor (pagamento, fraude ou autenticação).
`MEMBER_MULTIPLE_PROVIDER_TYPES`	`members[i]`	O membro combina tipos de provedores (por exemplo, pagamento + fraude ou pagamento + autenticação).
`PAYMENT_PROVIDER_ID_REQUIRED`	`members[i].payment_provider_id`	`merchant_payment_provider_id` enviado sem `payment_provider_id`.
`AUTHENTICATION_TYPE_REQUIRED`	`members[i].authentication_type`	Membro de autenticação sem um `authentication_type`.
`INVALID_AUTHENTICATION_TYPE`	`members[i].authentication_type`	Nenhum dos `3ds_authentication`, `3ds_data_only`, `unico_id` (aplica-se a `failover.authentication_type` também).
`FAILOVER_ONLY_ON_AUTHENTICATION`	`members[i].failover`	`failover` definido em um membro sem autenticação.
`DUPLICATE_MEMBER`	`members[i]`	O mesmo provedor aparece mais de uma vez na regra.
`DUPLICATE_MEMBER_SORT`	`members[i].sort`	Dois membros compartilham um `sort` value.
`INVALID_STRATEGY`	`members[i].strategy`	Não `cascade`.
`POST_AUTH_ONLY_FRAUD`	`members[i].post_authorization`	`post_authorization = true` em um membro não fraudulento.
`POST_AUTH_MUST_BE_LAST`	`members[i].post_authorization`	O `post_authorization` membro não é o último por `sort`.
`PROVIDER_NOT_AVAILABLE`	`members[i]`	O provedor (pagamento, fraude ou autenticação) não está habilitado para este comerciante.
`MERCHANT_PROVIDER_MISMATCH`	`members[i].merchant_payment_provider_id`	A conexão não pertence ao dado `payment_provider_id`.

Teste A/B

`code`	Típico `field`	Causa
`SPLIT_WEIGHTS_MUST_SUM_TO_100`	`children`	Criança `weight` os valores não somam `100`.

Fluxo de ponta a ponta#

O /triggers suporte de endpoint dois modos de integração - escolha o que melhor se adequa à quantidade de lógica de decisão que você deseja possuir. Ambos usam o mesmo endpoint e as mesmas regras; apenas o formato da resposta e o número de chamadas diferem. Selecione-o com mode a pedido (single é o padrão). De qualquer forma, você fecha o ciclo com um /feedback call.

Modo	Como funciona	Melhor quando
1 · Chamada única (orientado para o cliente)	Um `/triggers` chamada retorna o plano completo — a autenticação a ser executada (com failover) e o `actions` que mapeiam cada resultado para processo ou declínio. Você mesmo executa o plano.	Você deseja o menor número de viagens de ida e volta e se sente confortável em aplicar a decisão localmente.
2 · Guiado (motorizado)	Você liga `/triggers` e o motor retorna apenas o próxima etapa mais um `status`. Você executa e depois liga `/triggers` novamente com o resultado dessa etapa; o motor retorna para a próxima etapa. Repita até `status = completed`.	Você deseja que a DEUNA possua e centralize a lógica de decisão, passo a passo.

Modo 1 – chamada única

Você faz um solteiro /triggers ligue. Se você administra um provedor de fraude antes da DEUNA, inclua seu resultado nessa chamada. A resposta é independente: ela nomeia a autenticação a ser executada (com um failover se o primário não estiver disponível) e o ações que mapeiam o resultado da autenticação para o que fazer a seguir — processo com um provedor de pagamento ou declínio. Sua plataforma executa esse plano localmente e fecha o ciclo com um /feedback ligue - há nenhum segundo /triggers round-trip.

Passo a passo

(Opcional) Pontue com um provedor de fraude. Se sua configuração usa um provedor de fraude antecipadamente, capture sua pontuação/decisão para que possa ser correspondida por regras (por meio do fraud_risk opção ou metadata).
Solicite a recomendação (uma ligação). POST /routing/v1/triggers com os dados da transação (e o resultado da fraude, se houver). A resposta contém uma authentication bloco (primary + opcional failover) e um actions block.
Authenticate. Execute a autenticação recomendada (por exemplo, Autenticação 3DS, Somente dados 3DS ou ID Unico). Se o primary provedor não está disponível, use o failover.
Decida e processe. Aplicar actions: cada resultado é mapeado para process (com o provedor de pagamento mencionado na ação) ou decline; o default a ação se aplica quando nenhum outro resultado corresponde.
Relate o resultado. POST /routing/v1/feedback com o collection objeto e o attempts (resultado da autenticação + resultado do pagamento). Isso fecha o ciclo para análises e rotulagem de ML.

Os comerciantes com um único provedor de pagamento verão um provedor no process ação; lojistas com vários podem configurar uma cascata na regra members, e a recomendação reflete o(s) provedor(es) a ser(em) tentado(s).

Diagrama de sequência

Comerciante ou clienteProvedor ou processadorDEUNA

Resposta do Modo 1 – o plano completo

O /triggers resposta é uma recomendação única e independente: a authentication para executar (com um opcional failover) e o actions que mapeiam o resultado da autenticação para o que fazer. Sua plataforma executa isso 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	Descrição
`collection.id`	UUID	ID de correlação para esta avaliação. Ecoe `/feedback`.
`collection.prediction_id`	string	Identificador de ML para a recomendação. Ecoe `/feedback`.
`recommendation.rule_id`	integer	A regra que correspondeu (mesmo identificador do objeto de regra `id`).
`recommendation.rule_label`	string	Nome da regra legível por humanos.
`recommendation.authentication.primary`	object	A autenticação a ser executada primeiro: `{ "authentication_type": "3ds_authentication" }`. Usa o mesmo `authentication_type` valores como membros da regra.
`recommendation.authentication.failover`	objeto \| nulo	Autenticação de backup se o primário não estiver disponível.
`recommendation.actions`	object	Mapeia o resultado da autenticação para uma ação. Chaveado por resultado.
`recommendation.actions.<outcome>.action`	enumeração	`process` ou `decline`.
`recommendation.actions.<outcome>.provider`	string	Presente quando `action = process` — o nome do provedor de pagamento a ser usado, conforme configurado na sua regra (por exemplo, `acquirer_gateway`).
`recommendation.actions.default`	object	A ação de fallback é aplicada quando nenhuma outra chave de resultado corresponde.

Chaves de resultados abaixo actions descreva o resultado da autenticação ao qual eles se aplicam (por exemplo, on_success_with_liability_shift); default é o resumo.

Modo 2 – guiado (passo a passo)

Configure "mode": "guided" no pedido. Em vez do plano completo, o mecanismo retorna o próxima etapa e um status, e você conduz o fluxo uma etapa de cada vez:

status: awaiting_authentication → next_step informa qual autenticação executar.
status: awaiting_fraud → next_step informa qual verificação de fraude executar.
status: completed → o motor decidiu; next_step.action é process (com um provider) ou decline.

Depois de executar uma etapa, chame /triggers novamente - eco the collection da resposta anterior e inclua o resultado dessa etapa (authentication_result ou fraud_result). O motor avança e retorna para a próxima etapa. Repita até status = completed, então feche com /feedback.

Diagrama de sequência

Comerciante ou clienteDEUNA

Primeira resposta - uma etapa a ser executada

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

Solicitação de acompanhamento – poste o resultado da etapa

JSON

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

Resposta ao terminal — 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	Descrição
`mode`	enumeração	Campo de solicitação: `single` (padrão) ou `guided`.
`collection`	object	Campo de solicitação em chamadas guiadas de acompanhamento: ecoe o `collection` da resposta anterior para continuar a mesma avaliação.
`authentication_result` / `fraud_result`	object	Campo de solicitação: o resultado da etapa que você acabou de realizar.
`recommendation.status`	enumeração	`awaiting_authentication`, `awaiting_fraud`, ou `completed`.
`recommendation.next_step.type`	enumeração	`authentication`, `fraud`, `process`, ou `decline`.
`recommendation.next_step.authentication_type`	enumeração	Presente quando `type = authentication`.
`recommendation.next_step.failover`	objeto \| nulo	Backup opcional para uma etapa de autenticação.
`recommendation.next_step.provider`	string	Presente quando `type = process` — o provedor de pagamento a ser usado.

Ambos os modos são apoiados pelas mesmas regras e produzem as mesmas decisões – o modo guiado simplesmente pede à DEUNA um passo de cada vez, em vez de devolver todo o plano antecipadamente.

Identificação do cartão ativada `/triggers`

O cartão em payment_source.card_info pode ser fornecido uma das três maneiras:

Método	Campos	Notas
PAN completo	`card_number`	BIN e marca são derivados do lado do servidor.
BIN + últimos quatro	`bin` (8 dígitos), `last_four`	Use quando você não transmite o PAN completo. BIN de 8 dígitos fornece roteamento em nível de emissor.
Token de rede	`network_token`: `{ dpan, par, account_bin, cryptogram, eci }`	Para credenciais tokenizadas. Veja a nota abaixo sobre como obter dados em nível BIN.

Comentários `attempts` exemplo

attempts relata o que realmente aconteceu: o resultado da autenticação e, em seguida, o resultado do pagamento do seu provedor de pagamento (códigos 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 usa códigos de resposta ISO 8583 – por ex. "05" = não honre. eci e pares_status carregue o resultado 3DS; liability_shift indica se a autenticação mudou a responsabilidade.

Autenticação de backup (failover)

As regras podem definir um failover provedor de autenticação. Se o recomendado primary provedor não está disponível (por exemplo, o provedor de autenticação 3DS está inativo), a recomendação retorna o failover (por exemplo, somente dados 3DS) para que uma interrupção do provedor nunca deixe uma transação não autenticada.

Dúvidas ou detalhes faltando? Contate sua equipe de integração DEUNA.