Recommendation Engine — Integration Guide

Authentication

All endpoints authenticate with an API key sent in the X-Api-Key header — this is the only supported authentication scheme. Your merchant is resolved from the API key, so the merchant identifier does not appear in the URL.

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

Endpoint summary

Path parameters:

The Rule object

A rule is the core resource returned and accepted by these endpoints.

Triggers

The Condition object

Conditions define what a transaction must match. All conditions on a rule are combined with AND.

Example — match Mastercard-branded cards

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

The Member object

Members are the providers a matched rule uses, attempted in sort order (the cascade). A member references one provider — a payment provider, a fraud provider, or an authentication provider.

Example — payment-provider member

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

Example — fraud-provider member

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

Example — authentication-provider member (with failover)

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

A/B testing — split traffic between two routes

To A/B test, add two routes to a rule (as children) and give each a percentage weight. The engine sends that share of matching transactions to each route — e.g. 70% to Route A, 30% to Route B — so you can compare them on live traffic.

Rules:

• Exactly two routes.
• weight values must sum to 100.
• The rule must set ignore_next_rules: true.
• Assignment is sticky per transaction_id (a transaction always gets the same route), and the route that ran is echoed back in the /triggers response.

Example — 70/30 split

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

Create a rule

POST /routing/v1/rules

The example below creates a merchant_rule for Mastercard credit cards in MXN, runs a fraud check, and then branches by fraud_risk: block high, and route medium/low to 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 } ] }
    ]
  }'

Response 201

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

Returns a single rule, including its conditions, members and any children. rule_id is the numeric identifier.

cURL

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

Response 200

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

Errors: PAYROU-NOT_FOUND (404) if the rule does not exist; PAYROU-FORBIDDEN (403) if it is not accesible; PAYROU-INVALID_PATH_PARAM (400) if rule_id is not a valid integer.

List rules

GET /routing/v1/rules

Returns rules for your merchant in priority order. Results are paginated with an opaque cursor.

The response wraps the rules in a pagination object. Keep requesting with next_cursor while has_more is true.

cURL

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

Response 200

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

Update a rule

PUT /routing/v1/rules/{rule_id}

Full replace of the rule. Send the complete rule body — the same shape as create — including id and created_at. Common use: flip status between enabled and disabled (this is how you "retire" a rule instead of deleting).

cURL — disabling a rule

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

Response 200

Returns the updated rule with status now disabled. Note: condition ids are re-issued on update.

Change a rule's priority (reorder)

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

Moves a rule to a new priority. Other rules are re-sequenced accordingly.

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

Response 200

{ "priority": 2 }

Errors: PAYROU-VALIDATION (400) with errors[].code = PRIORITY_OUT_OF_RANGE if priority is not a non-negative integer.

Validations

Create and update run these checks. Any failure returns HTTP 400 with top-level code PAYROU-VALIDATION and one entry per offending field in errors[] (see Errors for the envelope and the full field-level code catalog).

Rule level

• status must be one of enabled, disabled, draft, process-in-background.
• trigger must be one of payment, reject, merchant_rule.
• trigger = payment → at least one member; no children.
• trigger = reject → no members, no children, ignore_next_rules must be false, is_default must be false.
• trigger = merchant_rule → at least one member or at least one child.
• is_default = true → no conditions and ignore_next_rules must be false.
• is_default = false → at least one condition.
• priority must be > 0 and ≤ 1000.

Conditions

• rule_option.id required (> 0); operand required (non-empty).
• operator must be valid for that rule option (see catalog).
• A rule_option may appear only once per rule (except metadata).
• For metadata (id 16): metadata_field_name and metadata_field_type required; type must be text or numeric.
• For operand_type = list: operand must be a valid list UUID that exists.

Members

• Each member must reference exactly one provider type: payment, merchant-payment, fraud, or authentication.
• Provider types cannot be mixed on one member.
• If merchant_payment_provider_id is present, payment_provider_id must also be present.
• Authentication members require authentication_type (one of 3ds_authentication, 3ds_data_only, unico_id).
• failover is valid only on authentication members; its authentication_type must also be a valid value.
• sort must be unique within the rule.
• A provider may appear only once per rule.
• strategy must be cascade.
• post_authorization = true only for fraud providers, and that member must be last by sort.

Service-level (checked against merchant configuration)

• Referenced rule option must exist and support the given operator.
• Referenced payment / merchant-payment / fraud / authentication provider must be enabled for the merchant.
• merchant_payment_provider_id must belong to the given payment_provider_id.

Errors

Error envelope

Every error response uses the same JSON shape:

{
  "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'."
    }
  ]
}

Always send an X-Idempotency-Key on writes. Replaying the same key returns the original response; reusing a key with a different body returns 409 PAYROU-CONFLICT.

HTTP status codes

Top-level codes

Validation codes

Returned inside errors[] when the top-level code is PAYROU-VALIDATION. Each is stable and safe to branch on.

Rule level

Conditions

Members

A/B testing

End-to-end flow

The /triggers endpoint supports two integration modes — pick whichever fits how much of the decision logic you want to own. Both use the same endpoint and the same rules; only the response shape and the number of calls differ. Select it with mode on the request (single is the default). Either way, you close the loop with one /feedback call.

Mode 1 — single call

You make a single /triggers call. If you run a fraud provider before DEUNA, include its result in that call. The response is self-contained: it names the authentication to run (with a failover if the primary is unavailable) and the actions that map the authentication result to what to do next — process with a payment provider or decline. Your platform executes that plan locally and closes the loop with one /feedback call — there is no second /triggers round-trip.

Step by step

1. (Optional) Score with a fraud provider. If your setup uses a fraud provider up front, capture its score/decision so it can be matched by rules (via the fraud_risk option or metadata).
2. Request the recommendation (one call). POST /routing/v1/triggers with the transaction data (and the fraud result, if any). The response contains an authentication block (primary + optional failover) and an actions block.
3. Authenticate. Run the recommended authentication (e.g. 3DS Authentication, 3DS Data Only, or Unico ID). If the primary provider is unavailable, use the failover.
4. Decide and process. Apply actions: each outcome maps to process (with the payment provider named in the action) or decline; the default action applies when no other outcome matches.
5. Report the outcome. POST /routing/v1/feedback with the collection object and the attempts (authentication result + payment result). This closes the loop for analytics and ML labeling.

Merchants with a single payment provider will see one provider in the process action; merchants with several can configure a cascade in the rule's members, and the recommendation reflects the provider(s) to attempt.

sequenceDiagram
    participant M as Your platform
    participant F as Fraud provider
    participant D as DEUNA Recommendation Engine
    M->>F: score request (if used)
    F-->>M: score + decision
    M->>D: One POST /routing/v1/triggers (txn data + fraud result)
    D-->>M: recommendation (auth route + failover + actions)
    Note over M: Run recommended auth use failover if primary down
    Note over M: Apply actions - process with payment provider, or decline
    M->>D: Two POST /routing/v1/feedback (auth result + payment result)
    D-->>M: 200 OK (outcome recorded, prediction ML labeled)

Mode 1 response — the full plan

The /triggers response is a single, self-contained recommendation: the authentication to run (with an optional failover) and the actions that map the authentication result to what to do. Your platform executes this locally.

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

Outcome keys under actions describe the authentication result they apply to (e.g. on_success_with_liability_shift); default is the catch-all.

Mode 2 — guided (step-by-step)

Set "mode": "guided" on the request. Instead of the full plan, the engine returns the next step and a status, and you drive the flow one step at a time:

• status: awaiting_authentication → next_step tells you which authentication to run.
• status: awaiting_fraud → next_step tells you which fraud check to run.
• status: completed → the engine has decided; next_step.action is process (with a provider) or decline.

After you perform a step, call /triggers again — echo the collection from the previous response and include that step's result (authentication_result or fraud_result). The engine advances and returns the next step. Repeat until status = completed, then close with /feedback.

sequenceDiagram
    participant M as Your platform (merchant / PSP)
    participant D as DEUNA Recommendation Engine
    M->>D: POST /routing/v1/triggers (mode=guided, txn data)
    D-->>M: status=awaiting_authentication · next_step: run 3ds_authentication
    Note over M: Run 3DS authentication
    M->>D: POST /routing/v1/triggers (collection + authentication_result)
    D-->>M: status=completed · next_step: process with acquirer_gateway
    Note over M: Process the payment
    M->>D: POST /routing/v1/feedback (attempts)
    D-->>M: 200 OK

First response — a step to perform

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

Follow-up request — post the step result

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

Terminal response — status = completed

{
  "collection": { "id": "c7b9e3a2-4d51-4f8a-9b21-6e0f2a1c8d34", "prediction_id": "pred_xyz789abc" },
  "recommendation": {
    "rule_id": 21866,
    "status": "completed",
    "next_step": { "type": "process", "provider": "acquirer_gateway" }
  }
}

Both modes are backed by the same rules and produce the same decisions — guided mode simply asks DEUNA for one step at a time instead of returning the whole plan up front.

Card identification on /triggers

The card in payment_source.card_info can be supplied one of three ways:

Feedback attempts example

attempts reports what actually happened: the authentication result, then the payment result from your payment provider (ISO 8583 codes).

{
  "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 uses ISO 8583 response codes — e.g. "05" = do not honor. eci and pares_status carry the 3DS outcome; liability_shift indicates whether the authentication shifted liability.

Backup authentication (failover)

Rules can define a failover authentication provider. If the recommended primary provider is unavailable (e.g. the 3DS Authentication provider is down), the recommendation returns the failover (e.g. 3DS Data Only) so a provider outage never leaves a transaction un-authenticated.

Questions or missing details? Contact your DEUNA integration team.