Routing Resource Shape

A routing tells Yuno, for one payment_method on one account, which connection to use — and lets you branch by buyer attributes (country, currency, amount, card brand, custom metadata, …).

Resource shape

{
  "id": "r_8f2c1d3e-…",
  "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": "DECLINED", "next": 2 }] },
          { "index": 2, "provider_id": "ADYEN",  "connection_id": "b2c4d5e6-…" }
        ]
      }
    },
    {
      "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	Inferred from your API key. Not supplied in request bodies.
`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, 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 one provider attempt. index values are contiguous starting at 1.

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	yes	Must match the `provider_id` of the referenced connection.
`connection_id`	UUID	yes	Must be `ACTIVE`, in the same account, and support the routing’s `payment_method`.
`output[]`	object[]	no	Per-outcome handlers. 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.

output[] entries

Field	Type	Required	Notes
`status`	enum	yes	What outcome this entry reacts to. See enum below.
`decline_types[]`	string[]	only with `status = DECLINE_GROUP`	Subset of Yuno’s normalized decline taxonomy.
`error_rate_threshold`	object	only with `status = ERROR_RATE`	`{ threshold_percent: int, window_seconds: int }`.
`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.	—
`DECLINED`	Any decline (catch-all). Place last in the array.	—
`DECLINE_GROUP`	Decline whose normalized code is in `decline_types[]`.	`decline_types[]`
`ERROR_RATE`	The step’s rolling error rate exceeds `error_rate_threshold`.	`error_rate_threshold`
`TIMEOUT`	The provider didn’t respond within Yuno’s per-step timeout.	—
`INTERNAL_ERROR`	The provider returned a 5xx or connection error before reaching the issuer.	—

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.
The provider call runs.
Yuno walks output[] top-to-bottom; the first entry whose status (plus optional decline_types / error_rate_threshold predicate) matches the outcome wins.
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.

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.

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Transaction Reporting

Routing Recommendations

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions Plans

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

FX Rates

Banking Connectivity

Webhooks

Resource shape

Percentage splits

​Resource shape

​Percentage splits

Resource shape

Percentage splits