Routing Resource Shape - Yuno API Documentation

A routing tells Yuno, for one payment_method on one account, which connections to use — payment providers, fraud screening, 3DS and authentication steps, or a smart routing step that picks the provider per payment — and lets you branch by buyer attributes (country, currency, amount, card brand, custom metadata, schedules, volume limits, …), react to each outcome (approval, decline, decline group, Merchant Advice Code, pending, error) and end the route with an action (cancel, capture, hold for review, revert).

Resource shape

{
  "id": "8f2c1d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "account_id": "acc-uuid",
  "payment_method": "CARD",
  "name": "Card routing",
  "default_route": {
    "steps": [
      { "index": 1, "provider_id": "STRIPE", "connection_id": "f1a3c4d5-…" }
    ]
  },
  "condition_sets": [
    {
      "sort_number": 1,
      "name": "US & Canada — high value",
      "description": "Route US/CA credit card transactions over $500",
      "conditions": [
        { "condition_type": "COUNTRY", "conditional": "ONE_OF",       "values": ["US", "CA"] },
        { "condition_type": "AMOUNT",  "conditional": "GREATER_THAN", "values": ["500"], "currency": "USD" }
      ],
      "route": {
        "steps": [
          { "index": 1, "provider_id": "STRIPE", "connection_id": "f1a3c4d5-…",
            "output": [
              { "status": "APPROVED",      "next": 3 },
              { "status": "DECLINE_GROUP", "group_id": 1044, "next": 2, "retry": true },
              { "status": "DECLINED",      "next": 2 }
            ] },
          { "index": 2, "provider_id": "ADYEN",  "connection_id": "b2c4d5e6-…",
            "output": [
              { "status": "APPROVED", "next": 3 }
            ] },
          { "index": 3, "action": "CAPTURE", "action_delay": "PT5M" }
        ]
      }
    },
    {
      "sort_number": 2,
      "name": "Brazil — split between three providers",
      "conditions": [
        { "condition_type": "COUNTRY", "conditional": "EQUAL", "values": ["BR"] }
      ],
      "route": {
        "start_split": [
          { "index": 1, "percentage": 45 },
          { "index": 2, "percentage": 45 },
          { "index": 3, "percentage": 10 }
        ],
        "steps": [
          { "index": 1, "provider_id": "ADYEN",  "connection_id": "b2c4d5e6-…",
            "output": [{ "status": "DECLINED",
                         "next_split": [{ "index": 2, "percentage": 70 }, { "index": 3, "percentage": 30 }] }] },
          { "index": 2, "provider_id": "STRIPE", "connection_id": "f1a3c4d5-…" },
          { "index": 3, "provider_id": "DLOCAL", "connection_id": "c3d5e6f7-…" }
        ]
      }
    }
  ],
  "created_at": "2026-05-12T12:00:00Z",
  "updated_at": "2026-05-12T12:00:00Z"
}

Top-level fields

Field	Type	Notes
`id`	UUID	Server-assigned. The same value is referenced as `routing_id` in URL paths.
`account_id`	string	The account the routing belongs to. Required in the `POST` and `PATCH` bodies; on `PATCH` it must be the routing’s own account.
`payment_method`	enum	E.g., `CARD`, `PIX`, `WALLET`. Immutable per routing — to route a different method, create a new routing.
`name`	string	Free-form label.
`default_route`	object	The route used when no `condition_sets[]` matches. Required.
`condition_sets[]`	object[]	Optional. Ordered by `sort_number` — first matching set wins. Each has one `route`.
`created_at`, `updated_at`	ISO-8601 timestamps	Server-managed.

route object

Field	Type	Required	Notes
`steps[]`	object[]	yes	The provider attempts and action steps, see below.
`start_split[]`	object[]	no	Splits the entry of the route across several steps by percentage. Omit to start every payment on `index: 1`. See Percentage splits.

route.steps[] Each step is a provider step (provider_id + connection_id: a payment, fraud, 3DS or authentication provider, see Provider step kinds), a smart routing step (provider_id: "SMART_ROUTING" + smart_routing, see Smart routing steps) or an action step (action). index values are contiguous starting at 1, counting every kind.

Field	Type	Required	Notes
`index`	int	yes	Step ordinal within the route. Cycles are forbidden — `output[].next` must point to a higher index.
`provider_id`	string	provider and smart routing steps	Must match the `provider_id` of the referenced connection; `SMART_ROUTING` on a smart routing step. Omit on an action step.
`connection_id`	UUID	provider steps	Must be `ACTIVE`, in the same account, and support the routing’s `payment_method`. Omit on action and smart routing steps.
`provider_type`	enum	response only	The kind the provider resolves to: `PAYMENT`, `FRAUD`, `THREE_D_SECURE`, `AUTHENTICATION`. Ignored on write.
`fraud`	object	no	Configuration of a fraud provider step: `rules`, `blocklists`, `allowlists`, `reviewlists`, `preset` (opaque codes taken from the dashboard) and `report_only`. Only on `FRAUD` providers. See Provider step kinds.
`smart_routing`	object	smart routing steps	`type`, `providers[]`, `no_retry_decline_types[]` and `no_retry_failure_causes[]`. See Smart routing steps.
`action`	enum	action steps	`CANCEL`, `CAPTURE`, `HOLD_FOR_REVIEW` or `REVERT`. See Action steps. Omit on provider steps.
`action_delay`	string	no	ISO-8601 duration, only with `action = CAPTURE`. How long after the approval Yuno captures. See Action steps.
`output[]`	object[]	no	Per-outcome handlers of a provider step. Omit for terminal steps with no chaining or per-decline customization — the route will just run the step and terminate with whatever the provider returned. Not allowed on an action step; responses return it as an empty array there.

output[] entries

Field	Type	Required	Notes
`status`	enum	yes	What outcome this entry reacts to. See enum below.
`decline_types[]`	string[]	see Outcome groups	Decline sub-statuses the entry reacts to. On `DECLINE_GROUP` it is required unless `group_id` is sent. Responses return it on `DECLINE_GROUP` and `MAC_CODE_GROUP` entries.
`group_id`	int	see Outcome groups	Id of a decline group, Merchant Advice Code group or succeeded group of the account. Required on `MAC_CODE_GROUP` and `SUCCEEDED_GROUP`; optional on `DECLINE_GROUP`. Not allowed on other statuses.
`group_name`	string	response only	Name of the group behind `group_id`, as shown in the dashboard. Ignored on write.
`retry`	boolean	no	`true` runs the same provider once more before this entry’s destination applies. Only on `DECLINED`, `INTERNAL_ERROR` and `DECLINE_GROUP`. Responses always return it. See Retry.
`next`	int \| null	no	Index of the step to jump to, or `null` to terminate. When `next_split` is set, Yuno returns `next` as its first entry and accepts it only with that value.
`next_split[]`	object[]	no	Splits the jump across several steps by percentage instead of a single `next`. See Percentage splits.

status enum

Value	Triggers when	Companion field
`APPROVED`	The provider returned success. Implicit by default; list explicitly only for post-approval routing, such as a `CAPTURE` or `HOLD_FOR_REVIEW` step.	—
`DECLINED`	Any decline (catch-all). Place last in the array.	—
`DECLINE_GROUP`	Decline whose normalized sub-status is in the group.	`group_id` and/or `decline_types[]`
`MAC_CODE_GROUP`	Decline whose normalized Merchant Advice Code is in the group.	`group_id`
`SUCCEEDED_GROUP`	Success whose sub-status is in the group — today that is `PENDING_IN_REVIEW`, an authorization the provider holds for manual review.	`group_id`
`PENDING`	A fraud, 3DS or authentication provider left the payment pending (a review to resolve, a challenge to complete). Only on those steps. See Provider step kinds.	—
`INTERNAL_ERROR`	The provider returned an error (5xx, connection failure, timeout) before reaching the issuer.	—

TIMEOUT and ERROR_RATE appeared in earlier versions of this page. They are not members of the status enum: sending either one rejects the whole routing with 400, and messages lists the allowed values. A provider timeout is handled by INTERNAL_ERROR.

Provider step kinds

The kind of a provider step is derived from its provider_id and returned as provider_type. It decides which outcomes the step can have and what may follow it, the same way the dashboard does.

`provider_type`	Providers	Outcomes	Notes
`PAYMENT`	Acquirers and PSPs (`STRIPE`, `ADYEN`, `DLOCAL`, …)	`APPROVED`, `DECLINED`, `DECLINE_GROUP`, `MAC_CODE_GROUP`, `SUCCEEDED_GROUP`, `INTERNAL_ERROR`	The payment attempt. Approvals may continue to a `CAPTURE` / `HOLD_FOR_REVIEW` step or to a fraud step that runs after the payment.
`FRAUD`	Fraud screening (`CYBERSOURCE`, `SIGNIFYD`, `FORTER`, `CLEAR_SALE`, `RISKIFIED`, `YUNO_FRAUD_SCREENING`, …)	`APPROVED`, `DECLINED`, `PENDING`, `INTERNAL_ERROR`	Before the payment (the route enters on it, or it follows another fraud, 3DS or authentication step): `PENDING` may continue to another step. After the payment (reached from an output of a payment or smart routing step): `PENDING` is terminal and the step may continue to a `REVERT` action.
`THREE_D_SECURE`	3DS servers (`NETCETERA_3DS`, `CHECKOUT_3DS`, `CYBERSOURCE_3DS`, …)	`APPROVED`, `DECLINED`, `PENDING`, `INTERNAL_ERROR`	`PENDING` is the challenge pending its result and may continue to another step.
`AUTHENTICATION`	`NETWORK_TOKEN_AUTHENTICATION`	`APPROVED`, `DECLINED`, `PENDING`, `INTERNAL_ERROR`	Same rules as 3DS.

PENDING on a PAYMENT or smart routing step is rejected with 400 INVALID_ROUTE_CONFIGURATION (output PENDING is only supported on fraud, 3DS and authentication provider steps), and so is a PENDING that continues to another step on a fraud step that runs after the payment. Fraud configuration. A FRAUD step carries the same configuration the dashboard edits, in the fraud object:

Field	Type	Notes
`rules`, `blocklists`, `allowlists`, `reviewlists`, `preset`	string	The codes of the rules, lists and preset the step applies, exactly as the dashboard stores them (comma-separated codes where it holds several). Yuno keeps them as given and never validates them against the fraud provider; copy them from the step’s configuration in the dashboard until a listing endpoint exists.
`report_only`	boolean	The step scores the payment without acting on the result. Only on a fraud step that is not the route entry and is reached only from `DECLINED`, `DECLINE_GROUP` or `MAC_CODE_GROUP` outputs of a payment step; anything else is `400 INVALID_ROUTE_CONFIGURATION`.

Responses return fraud on every FRAUD step (fields without a value are omitted, report_only always). On Update a Routing a fraud step sent without fraud keeps its stored configuration; a step sent with it replaces all six fields. fraud on a step that is not a fraud provider is rejected. Evaluation rules

The route enters at index: 1, unless start_split is set — then Yuno draws one entry step per payment according to the percentages. If the entry step is a CANCEL step, the payment is rejected and the route ends.
The provider call runs.
Yuno walks output[] top-to-bottom; the first entry whose status (plus the group predicate on DECLINE_GROUP, MAC_CODE_GROUP and SUCCEEDED_GROUP) matches the outcome wins. An entry with retry: true runs the same provider once more first; the outcome of that second attempt decides.
If the matched entry has next, jump to that step. If it has next_split, Yuno draws one of its steps per payment according to the percentages and jumps there. If neither is set or no entry matches, the route terminates with the actual provider outcome.
A jump to an action step performs the action (CANCEL, CAPTURE, HOLD_FOR_REVIEW) and ends the route.

Outcome groups

A group is a named set of outcomes you keep on the account, so several routes can react to the same list without repeating it. The dashboard shows them under the routing settings; the API reads them with List Decline Groups and List Succeeded Groups and references them by group_id.

`status`	Group kind	Members	How to reference it
`DECLINE_GROUP`	Decline group	Decline sub-statuses, such as `DECLINED_BY_BANK` or `INSUFFICIENT_FUNDS`. Full list under Declined status.	`group_id` of an existing group, or `decline_types[]` alone to let Yuno create one.
`MAC_CODE_GROUP`	Merchant Advice Code group	Normalized MAC values, such as `NO_RETRY_POLICY` or `RETRY_AFTER_24_H`. Full list under Merchant Advice Codes.	`group_id` of an existing group.
`SUCCEEDED_GROUP`	Succeeded group	Success sub-statuses. Today the only member is `PENDING_IN_REVIEW`.	`group_id` of an existing group.

Rules:

group_id must be a group of the routing’s account and of the kind the status expects. An unknown id, an id of another account, or a Merchant Advice Code group sent as DECLINE_GROUP is rejected with 400 INVALID_ROUTE_CONFIGURATION; messages names the group_id and the kind it actually is.
DECLINE_GROUP with decline_types[] and no group_id keeps working as before: Yuno creates a decline group named auto_… with those sub-statuses on every save. Prefer group_id when the group already exists, so the account does not accumulate automatic groups.
DECLINE_GROUP with both group_id and decline_types[] is accepted only when the list equals the group’s members as a set (order does not matter). This is what lets you send a retrieved routing back unchanged, since responses return both. A different list is rejected: edit the group in the dashboard instead.
MAC_CODE_GROUP and SUCCEEDED_GROUP require group_id; SUCCEEDED_GROUP does not accept decline_types[]. Create those groups in the dashboard first.
The same group_id cannot appear twice in the output[] of one step.
Responses return group_id and group_name on every group entry, and decline_types[] on DECLINE_GROUP and MAC_CODE_GROUP entries, in the same sub-status vocabulary the listing endpoints use.

Retry

retry: true on a DECLINED, INTERNAL_ERROR or DECLINE_GROUP entry tells Yuno to attempt the same provider once more when that outcome happens, before following the entry’s next / next_split. The second attempt uses the step’s other outputs as usual: if it is approved, the APPROVED path applies; if it fails again, the original destination of the entry applies. There is at most one retry per entry per payment.

retry: true on APPROVED, MAC_CODE_GROUP or SUCCEEDED_GROUP is rejected with 400 INVALID_ROUTE_CONFIGURATION; retry: false is accepted anywhere, which is what lets you send a retrieved routing back unchanged.
Responses always return retry on every entry (false when not set), so you can see which branches retry.
On Update a Routing, an entry sent without retry keeps the value already stored for that position; send retry: false explicitly to turn a retry off.

Action steps

An action step ends the route with an action instead of calling a provider. It has index and action, no provider_id, connection_id or output, and it counts in the contiguous index sequence.

{ "index": 3, "action": "CAPTURE", "action_delay": "PT5M" }

`action`	What happens at payment time	Where it can sit
`CANCEL`	The payment is rejected without calling any (further) provider. The payment ends `REJECTED` with a `YUNO_ROUTING` transaction and response code `YUNO_ROUTING_REJECTED`.	As the only step of a route (reject every payment that lands on it), or as the destination of a `DECLINED`, `INTERNAL_ERROR`, `DECLINE_GROUP`, `MAC_CODE_GROUP` or `PENDING` entry. Never after an `APPROVED` or `SUCCEEDED_GROUP` output of a payment step: the provider already approved, so rejecting the payment in Yuno would leave the two out of sync.
`CAPTURE`	Captures the authorization after `action_delay`. Applies to payments created as authorizations (`capture: false`); a payment that was already captured is left as it is.	Only as the destination of `APPROVED` or `SUCCEEDED_GROUP` entries of a payment or smart routing step. Not as the route entry, not from any other status or kind of step.
`HOLD_FOR_REVIEW`	Leaves the authorization pending manual review in the dashboard; Yuno does not capture it automatically. Meaningful for an authorization the provider holds for review (`PENDING_IN_REVIEW`, a `SUCCEEDED_GROUP`).	Same placement as `CAPTURE`.
`REVERT`	Reverts the authorization after a fraud screening that ran after the payment (the dashboard’s post-authorization fraud step).	Only as the destination of the `APPROVED`, `DECLINED` or `INTERNAL_ERROR` entries of a fraud step that runs after the payment.

action_delay rules:

Only with action = CAPTURE; on any other step it is rejected.
ISO-8601 duration (PT5M, PT3H, P2D, P1W), at least 1 minute (PT1M) and at most 7 days (P7D).
Omit it to capture as soon as the approval is processed (about one minute).

A step that breaks these placement rules is rejected with 400 INVALID_ROUTE_CONFIGURATION; messages names the step and the rule (step index=N with action=CAPTURE must be reached only from an APPROVED or SUCCEEDED_GROUP output of a payment step, ... action=REVERT must be reached only from an output of a fraud step that runs after the payment, ... action=CANCEL must not be reached from an APPROVED or SUCCEEDED_GROUP output of a payment step). A CAPTURE, HOLD_FOR_REVIEW or REVERT step placed as the route entry or inside a start_split is rejected too. On Update a Routing, a stored CAPTURE or HOLD_FOR_REVIEW step is kept when the request leaves it out and the output it hung from is sent without next, and a CAPTURE step sent without action_delay keeps the stored delay, the same “stored wins” rule as retry. To change the capture, send the step with its new action_delay; to remove it, point that output at another step. Leaving the step out of the request does not remove it.

Smart routing steps

A smart routing step lets Yuno pick the provider per payment among a set of connections, by cost or by latency, instead of fixing one. It is the API form of the dashboard’s Smart Routing box. Unlike CAPTURE and HOLD_FOR_REVIEW, the step belongs to the request: an update that does not carry it removes it, so retrieve the routing first and send the step back when you change something else. See Update a Routing.

{
  "index": 2,
  "provider_id": "SMART_ROUTING",
  "smart_routing": {
    "type": "LATENCY",
    "providers": [
      { "provider_id": "ADYEN",  "connection_id": "b2c4d5e6-…", "network_token_on": true },
      { "provider_id": "STRIPE", "connection_id": "f1a3c4d5-…" }
    ],
    "no_retry_decline_types": ["DO_NOT_HONOR"]
  },
  "output": [{ "status": "APPROVED", "next": 3 }]
}

Field	Type	Required	Notes
`type`	enum	yes	`COSTS` (cheapest connection first) or `LATENCY` (fastest first). `COSTS` requires every listed connection to be active with its costs configured, including the “All other payments” cost.
`providers[]`	object[]	yes	Two to four payment providers, each `{ provider_id, connection_id, network_token_on }`, with distinct connections. Fraud, 3DS and authentication providers are not allowed here. `network_token_on` requires the organization to be onboarded to network tokens and the provider to support them.
`no_retry_decline_types[]`	string[]	no	Decline sub-statuses after which Yuno does not try the next provider of the set. A decline group chosen in the dashboard is returned expanded into its sub-statuses, and an update stores the list as sent.
`no_retry_failure_causes[]`	string[]	no	Failure causes (for example `PROVIDER_TIMEOUT`) after which Yuno does not try the next provider of the set.

Rules, the same the dashboard applies:

Only on routings with payment_method = "CARD", and at most one smart routing step per route.
The step has no connection_id and no action, and its output[] is at most one APPROVED entry. That entry may continue to a fraud step that runs after the payment (which must not route further) or to a CAPTURE / HOLD_FOR_REVIEW step; declines and errors are handled inside the step.
It must be reachable from step 1. Only fraud, 3DS or authentication steps may lead into it, each through its APPROVED or DECLINED outputs and routing every next it has to that same step.
A rule violation is 400 INVALID_ROUTE_CONFIGURATION; a missing cost configuration or an unsupported network token is 400 with NETWORK_TOKEN_NOT_ONBOARDED / NETWORK_TOKEN_NOT_SUPPORTED.

Responses return the step in the same shape. On update the request replaces the step; it is not kept when left out.

Percentage splits

Both start_split and output[].next_split are lists of { "index", "percentage" } entries:

Field	Type	Notes
`index`	int	The `steps[].index` to send traffic to. Must exist in the same route and, for `next_split`, be greater than the step that owns the output (routes only move forward).
`percentage`	int	Integer between `0` and `100`. The entries of one split must sum to exactly `100`.

How a split is resolved: the split is evaluated once per payment, before the step runs. For a next_split of [{ "index": 2, "percentage": 70 }, { "index": 3, "percentage": 30 }], roughly 70% of the payments that hit that output continue on step 2 and 30% on step 3; each individual payment follows exactly one branch. Over many payments the traffic converges to the configured percentages. Rules:

start_split needs at least one entry. A single entry with percentage: 100 is the explicit way to send all traffic to one step; omitting start_split means 100% on index: 1.
next_split needs at least two entries. For a single destination use next. next is optional next to next_split; if you send both, next must be the first entry of next_split. Responses always include next = first entry alongside next_split, so clients that only read next keep a fallback.
Every step must be reachable from the entry, through start_split, next or next_split.
A percentage of 0 is allowed, so you can keep a step in the configuration while it receives no traffic.
Percentages are integers. Decimals are rejected.
A split that breaks one of these rules is rejected with 400 INVALID_ROUTE_CONFIGURATION; messages names the split and the rule. A wrong shape (a decimal percentage, a missing percentage, a single-entry next_split) is rejected before that with 400 INVALID_PARAMETERS / BAD_REQUEST.

Update a Routing replaces the full configuration, splits included. A condition set sent without start_split goes back to a single entry on step 1, and an output sent without next_split keeps only the next it declares, so omitting a split is how you remove it. Retrieve a Routing always returns the current start_split and next_split, so a read-modify-write flow keeps them unless you drop them on purpose.

What the API does not show

A few things the dashboard can configure have no representation here: the REFUND, DECLINE and END actions (not step actions in the dashboard either), the per-step provider settings (timeout, network token, 3DS exemptions) and the monitors, and an action step placed where the placement rules do not allow it.

Retrieve a Routing leaves those steps and branches out of the response.
Update a Routing does not delete them: what the response cannot show is kept exactly as stored, grafted onto the step it hung from, so a retrieve → update round trip keeps the routing as it was. One exception: a currency condition built in the dashboard with an operator other than EQUAL or with several currencies has no AMOUNT form; it reads back as raw CURRENCY_AND_AMOUNT rows and an update that sends them back is rejected with 400 INVALID_ROUTE_CONFIGURATION. Edit that condition in the dashboard, or replace it with an AMOUNT condition on a single currency. The per-step provider settings follow the provider step with the same provider_id and connection_id; if you replace that connection, they go with it. A stored layout the merge cannot re-attach safely (the route enters on a hidden step, an output splits traffic between a hidden and a visible step, or a hidden step continues to a visible provider) is rejected with 400 INVALID_ROUTE_CONFIGURATION and a message that ends with “Edit this routing in the dashboard”.
To change any of those parts, use the dashboard.

​Resource shape

​Provider step kinds

​Outcome groups

​Retry

​Action steps

​Smart routing steps

​Percentage splits

​What the API does not show

Resource shape

Provider step kinds

Outcome groups

Retry

Action steps

Smart routing steps

Percentage splits

What the API does not show