Routing
Create a Routing
Creates a routing for one (account_id, payment_method) pair. Always live on success.
POST
/
routing
Create a Routing
curl --request POST \
--url https://api-sandbox.y.uno/v1/routing \
--header 'Content-Type: application/json' \
--header 'PRIVATE-SECRET-KEY: <api-key>' \
--header 'PUBLIC-API-KEY: <api-key>' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--data '
{
"account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
"payment_method": "GOOGLE_PAY",
"name": "Google Pay routing",
"default_route": {
"steps": [
{
"index": 1,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{
"status": "APPROVED",
"next": 3
},
{
"status": "DECLINED",
"retry": false,
"next_split": [
{
"index": 2,
"percentage": 70
},
{
"index": 4,
"percentage": 30
}
]
}
]
},
{
"index": 2,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{
"status": "APPROVED",
"next": 3
}
]
},
{
"index": 3,
"action": "CAPTURE",
"action_delay": "PT5M"
},
{
"index": 4,
"action": "CANCEL"
}
]
},
"condition_sets": [
{
"sort_number": 1,
"name": "US & Canada",
"conditions": [
{
"condition_type": "COUNTRY",
"conditional": "ONE_OF",
"values": [
"US",
"CA"
]
}
],
"route": {
"steps": [
{
"index": 1,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
}
]
}
}
]
}
'import requests
url = "https://api-sandbox.y.uno/v1/routing"
payload = {
"account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
"payment_method": "GOOGLE_PAY",
"name": "Google Pay routing",
"default_route": { "steps": [
{
"index": 1,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{
"status": "APPROVED",
"next": 3
},
{
"status": "DECLINED",
"retry": False,
"next_split": [
{
"index": 2,
"percentage": 70
},
{
"index": 4,
"percentage": 30
}
]
}
]
},
{
"index": 2,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{
"status": "APPROVED",
"next": 3
}
]
},
{
"index": 3,
"action": "CAPTURE",
"action_delay": "PT5M"
},
{
"index": 4,
"action": "CANCEL"
}
] },
"condition_sets": [
{
"sort_number": 1,
"name": "US & Canada",
"conditions": [
{
"condition_type": "COUNTRY",
"conditional": "ONE_OF",
"values": ["US", "CA"]
}
],
"route": { "steps": [
{
"index": 1,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
}
] }
}
]
}
headers = {
"X-Idempotency-Key": "<x-idempotency-key>",
"PUBLIC-API-KEY": "<api-key>",
"PRIVATE-SECRET-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Idempotency-Key': '<x-idempotency-key>',
'PUBLIC-API-KEY': '<api-key>',
'PRIVATE-SECRET-KEY': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
account_id: '7825fc5e-e50a-4248-9ae8-5d3786afb0be',
payment_method: 'GOOGLE_PAY',
name: 'Google Pay routing',
default_route: {
steps: [
{
index: 1,
provider_id: 'ADYEN',
connection_id: 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f',
output: [
{status: 'APPROVED', next: 3},
{
status: 'DECLINED',
retry: false,
next_split: [{index: 2, percentage: 70}, {index: 4, percentage: 30}]
}
]
},
{
index: 2,
provider_id: 'ADYEN',
connection_id: 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f',
output: [{status: 'APPROVED', next: 3}]
},
{index: 3, action: 'CAPTURE', action_delay: 'PT5M'},
{index: 4, action: 'CANCEL'}
]
},
condition_sets: [
{
sort_number: 1,
name: 'US & Canada',
conditions: [{condition_type: 'COUNTRY', conditional: 'ONE_OF', values: ['US', 'CA']}],
route: {
steps: [
{
index: 1,
provider_id: 'ADYEN',
connection_id: 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f'
}
]
}
}
]
})
};
fetch('https://api-sandbox.y.uno/v1/routing', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.y.uno/v1/routing",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'account_id' => '7825fc5e-e50a-4248-9ae8-5d3786afb0be',
'payment_method' => 'GOOGLE_PAY',
'name' => 'Google Pay routing',
'default_route' => [
'steps' => [
[
'index' => 1,
'provider_id' => 'ADYEN',
'connection_id' => 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f',
'output' => [
[
'status' => 'APPROVED',
'next' => 3
],
[
'status' => 'DECLINED',
'retry' => false,
'next_split' => [
[
'index' => 2,
'percentage' => 70
],
[
'index' => 4,
'percentage' => 30
]
]
]
]
],
[
'index' => 2,
'provider_id' => 'ADYEN',
'connection_id' => 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f',
'output' => [
[
'status' => 'APPROVED',
'next' => 3
]
]
],
[
'index' => 3,
'action' => 'CAPTURE',
'action_delay' => 'PT5M'
],
[
'index' => 4,
'action' => 'CANCEL'
]
]
],
'condition_sets' => [
[
'sort_number' => 1,
'name' => 'US & Canada',
'conditions' => [
[
'condition_type' => 'COUNTRY',
'conditional' => 'ONE_OF',
'values' => [
'US',
'CA'
]
]
],
'route' => [
'steps' => [
[
'index' => 1,
'provider_id' => 'ADYEN',
'connection_id' => 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"PRIVATE-SECRET-KEY: <api-key>",
"PUBLIC-API-KEY: <api-key>",
"X-Idempotency-Key: <x-idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.y.uno/v1/routing"
payload := strings.NewReader("{\n \"account_id\": \"7825fc5e-e50a-4248-9ae8-5d3786afb0be\",\n \"payment_method\": \"GOOGLE_PAY\",\n \"name\": \"Google Pay routing\",\n \"default_route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n },\n {\n \"status\": \"DECLINED\",\n \"retry\": false,\n \"next_split\": [\n {\n \"index\": 2,\n \"percentage\": 70\n },\n {\n \"index\": 4,\n \"percentage\": 30\n }\n ]\n }\n ]\n },\n {\n \"index\": 2,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n }\n ]\n },\n {\n \"index\": 3,\n \"action\": \"CAPTURE\",\n \"action_delay\": \"PT5M\"\n },\n {\n \"index\": 4,\n \"action\": \"CANCEL\"\n }\n ]\n },\n \"condition_sets\": [\n {\n \"sort_number\": 1,\n \"name\": \"US & Canada\",\n \"conditions\": [\n {\n \"condition_type\": \"COUNTRY\",\n \"conditional\": \"ONE_OF\",\n \"values\": [\n \"US\",\n \"CA\"\n ]\n }\n ],\n \"route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n }\n ]\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
req.Header.Add("PUBLIC-API-KEY", "<api-key>")
req.Header.Add("PRIVATE-SECRET-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.y.uno/v1/routing")
.header("X-Idempotency-Key", "<x-idempotency-key>")
.header("PUBLIC-API-KEY", "<api-key>")
.header("PRIVATE-SECRET-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"account_id\": \"7825fc5e-e50a-4248-9ae8-5d3786afb0be\",\n \"payment_method\": \"GOOGLE_PAY\",\n \"name\": \"Google Pay routing\",\n \"default_route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n },\n {\n \"status\": \"DECLINED\",\n \"retry\": false,\n \"next_split\": [\n {\n \"index\": 2,\n \"percentage\": 70\n },\n {\n \"index\": 4,\n \"percentage\": 30\n }\n ]\n }\n ]\n },\n {\n \"index\": 2,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n }\n ]\n },\n {\n \"index\": 3,\n \"action\": \"CAPTURE\",\n \"action_delay\": \"PT5M\"\n },\n {\n \"index\": 4,\n \"action\": \"CANCEL\"\n }\n ]\n },\n \"condition_sets\": [\n {\n \"sort_number\": 1,\n \"name\": \"US & Canada\",\n \"conditions\": [\n {\n \"condition_type\": \"COUNTRY\",\n \"conditional\": \"ONE_OF\",\n \"values\": [\n \"US\",\n \"CA\"\n ]\n }\n ],\n \"route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n }\n ]\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.y.uno/v1/routing")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["PUBLIC-API-KEY"] = '<api-key>'
request["PRIVATE-SECRET-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"account_id\": \"7825fc5e-e50a-4248-9ae8-5d3786afb0be\",\n \"payment_method\": \"GOOGLE_PAY\",\n \"name\": \"Google Pay routing\",\n \"default_route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n },\n {\n \"status\": \"DECLINED\",\n \"retry\": false,\n \"next_split\": [\n {\n \"index\": 2,\n \"percentage\": 70\n },\n {\n \"index\": 4,\n \"percentage\": 30\n }\n ]\n }\n ]\n },\n {\n \"index\": 2,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n }\n ]\n },\n {\n \"index\": 3,\n \"action\": \"CAPTURE\",\n \"action_delay\": \"PT5M\"\n },\n {\n \"index\": 4,\n \"action\": \"CANCEL\"\n }\n ]\n },\n \"condition_sets\": [\n {\n \"sort_number\": 1,\n \"name\": \"US & Canada\",\n \"conditions\": [\n {\n \"condition_type\": \"COUNTRY\",\n \"conditional\": \"ONE_OF\",\n \"values\": [\n \"US\",\n \"CA\"\n ]\n }\n ],\n \"route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n }\n ]\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "8f2c1d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"account_id": "acc-uuid",
"payment_method": "CARD",
"name": "Card routing",
"default_route": {
"start_split": [
{
"index": 1,
"percentage": 45
}
],
"steps": [
{
"index": 1,
"provider_id": "STRIPE",
"connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
"provider_type": "PAYMENT",
"action": "CANCEL",
"action_delay": "PT5M",
"output": [
{
"status": "DECLINED",
"decline_types": [
"<string>"
],
"group_id": 1044,
"group_name": "Soft declines",
"retry": false,
"next": 2,
"next_split": [
{
"index": 2,
"percentage": 70
}
]
}
],
"fraud": {
"rules": "rule-a,rule-b",
"blocklists": "<string>",
"allowlists": "<string>",
"reviewlists": "<string>",
"preset": "<string>",
"report_only": true
},
"smart_routing": {
"type": "LATENCY",
"providers": [
{
"provider_id": "ADYEN",
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"network_token_on": true
}
],
"no_retry_decline_types": [
"<string>"
],
"no_retry_failure_causes": [
"<string>"
]
}
}
]
},
"condition_sets": [
{
"sort_number": 1,
"name": "High Value US",
"description": "<string>",
"conditions": [
{
"condition_type": "COUNTRY",
"conditional": "ONE_OF",
"values": [
"US",
"CA"
],
"key": "<string>",
"currency": "USD",
"time_period_repeat_amount": 1,
"time_period_repeat_frequency": "DAILY",
"time_period_repetition_days": [
"MONDAY"
],
"time_period_start_time": "09:00:00",
"time_period_end_time": "18:00:00",
"timezone": "-03:00",
"limit_by": "PAYMENTS",
"payments_count": "ALL"
}
],
"route": {}
}
],
"created_at": "2026-05-12T14:30:00Z",
"updated_at": "2026-05-12T14:30:00Z"
}{
"code": "INVALID_ROUTE_CONFIGURATION",
"messages": [
"step index=2 with action=CAPTURE must be reached only from an APPROVED output of a provider step"
]
}{
"code": "NOT_AUTHENTICATED",
"messages": [
"Not authenticated"
]
}{
"code": "ROUTING_ALREADY_EXISTS",
"messages": [
"A routing already exists for this payment method"
]
}Creates a routing for one
(account_id, payment_method) pair. Each routing references connections by their connection_id. Make sure your connections are created and ACTIVE for the requested payment_method before you call routing. Outputs that reference a decline, Merchant Advice Code or succeeded group by group_id need that group to exist on the account too — see Outcome groups.
Body
string (UUID)
required
The merchant account ID this routing rule applies to.
enum
required
E.g.,
CARD, PIX, WALLET. Immutable per routing — to route a different method, create a new routing.string
required
Free-form label.
object
required
The route used when no
condition_sets[] matches.Show properties
Show properties
object[]
Optional. Splits the entry of the route across several steps by percentage, as
[{ "index": 1, "percentage": 45 }, { "index": 2, "percentage": 55 }]. Percentages are integers that must sum to 100. Omit to start every payment on step 1. See Percentage splits.object[]
required
Each step is either one provider attempt or an action step.
index values are contiguous starting at 1.Show item
Show item
integer
required
Step ordinal.
string
Required on provider steps (a payment, fraud, 3DS or authentication provider) and
SMART_ROUTING on a smart routing step; omit on an action step. Must match the provider of the connection.UUID
Required on provider steps; omit on action and smart routing steps. Must be
ACTIVE and support the payment_method.object
Configuration of a fraud provider step:
rules, blocklists, allowlists, reviewlists, preset (codes copied from the dashboard, kept as given) and report_only. Only on FRAUD providers. See Provider step kinds.object
Makes the step a smart routing step:
type (COSTS or LATENCY), providers (two to four { provider_id, connection_id, network_token_on } payment providers), no_retry_decline_types and no_retry_failure_causes. Card routings only, one per route. See Smart routing steps.enum
Makes the step an action step:
CANCEL rejects the payment, CAPTURE captures the authorization, HOLD_FOR_REVIEW leaves it pending manual review, REVERT reverts it after a fraud screening that ran after the payment. CAPTURE and HOLD_FOR_REVIEW are reached only from APPROVED or SUCCEEDED_GROUP outputs of a payment or smart routing step, REVERT only from the outputs of a fraud step that runs after the payment, and CANCEL never from an approval. An action step has no provider_id, connection_id or output. See Action steps.string
Only with
action = CAPTURE. ISO-8601 duration between the approval and the capture, at least PT1M and at most P7D (e.g. PT5M, PT3H, P2D). Omit to capture as soon as the approval is processed.object[]
Defines how to handle each possible outcome of this step. Not allowed on an action step.
Show item
Show item
string
required
The outcome status that triggers this rule:
APPROVED, DECLINED, DECLINE_GROUP, MAC_CODE_GROUP, SUCCEEDED_GROUP, PENDING (fraud, 3DS and authentication steps only) or INTERNAL_ERROR.integer
Id of a group of the account, from List Decline Groups or List Succeeded Groups. Required when
status is MAC_CODE_GROUP or SUCCEEDED_GROUP; optional on DECLINE_GROUP; not allowed otherwise. The group must be of the kind the status expects.string[]
Decline sub-statuses (e.g.,
INSUFFICIENT_FUNDS, DECLINED_BY_BANK). On DECLINE_GROUP, required unless group_id is sent; with group_id, it must equal the group’s members. Not allowed on SUCCEEDED_GROUP.boolean
true attempts the same provider once more when this outcome happens, before following next. Only on DECLINED, INTERNAL_ERROR and DECLINE_GROUP. Defaults to false.integer
The
index of the next step to execute. Omit if no fallback is needed. Optional next to next_split; if both are sent it must be the first next_split entry.object[]
Splits the fallback across several steps by percentage, as
[{ "index": 2, "percentage": 70 }, { "index": 3, "percentage": 30 }]. At least two entries, integer percentages that sum to 100. next is not required with it.object[]
Optional. Ordered by
sort_number — first matching set wins.Show item
Show item
integer
required
Priority of the condition set.
string
required
Label for the set.
object[]
required
List of Conditions that must match. Besides
condition_type, conditional, values, key and currency, a TIME_PERIOD condition carries its schedule fields and a VOLUME_PAYMENTS_LIMIT condition its limit_by, payments_count and period fields.object
required
The steps to execute if this set matches. Same shape as
default_route, including start_split, output[].next_split and action steps; a route made of a single CANCEL step rejects the matching payments.Response
string
Unique identifier for the routing.
string
Unique identifier for the account.
enum
The payment method this routing applies to (e.g.,
CARD).string
Label for the routing.
object
The default routing logic, in the shape described in Retrieve a Routing.
object[]
Optional conditional logic.
string
ISO 8601 timestamp.
string
ISO 8601 timestamp.
curl -X POST 'https://api.y.uno/v1/routing' \
-H 'public-api-key: <YOUR_PUBLIC_KEY>' \
-H 'private-secret-key: <YOUR_SECRET_KEY>' \
-H 'Content-Type: application/json' \
-H 'X-Idempotency-Key: <UUID>' \
-d '{
"account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
"payment_method": "CARD",
"name": "Card routing — Stripe primary, Adyen fallback",
"default_route": {
"steps": [
{
"index": 1,
"provider_id": "STRIPE",
"connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
"output": [
{ "status": "DECLINE_GROUP", "group_id": 1044, "next": 2, "retry": true },
{ "status": "MAC_CODE_GROUP", "group_id": 4542 },
{ "status": "DECLINED", "next": 2 },
{ "status": "INTERNAL_ERROR", "next": 2 }
]
},
{
"index": 2,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
}
]
},
"condition_sets": [
{
"sort_number": 1,
"name": "Reject foreign-issued cards",
"conditions": [
{ "condition_type": "CARD_ISSUER_COUNTRY", "conditional": "NOT_ONE_OF", "values": ["BR"] }
],
"route": {
"steps": [
{ "index": 1, "action": "CANCEL" }
]
}
},
{
"sort_number": 2,
"name": "Brazil — BRL 300 to 600 via Adyen, capture after 5 minutes",
"description": "BR card transactions between BRL 300 and 600 go to Adyen directly",
"conditions": [
{ "condition_type": "COUNTRY", "conditional": "EQUAL", "values": ["BR"] },
{ "condition_type": "AMOUNT", "conditional": "BETWEEN", "values": ["300.00", "600.00"], "currency": "BRL" }
],
"route": {
"steps": [
{ "index": 1, "provider_id": "ADYEN", "connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{ "status": "APPROVED", "next": 2 },
{ "status": "SUCCEEDED_GROUP", "group_id": 430 }
] },
{ "index": 2, "action": "CAPTURE", "action_delay": "PT5M" }
]
}
},
{
"sort_number": 3,
"name": "Mexico — 45/45/10 between Adyen, Stripe and dLocal",
"conditions": [
{ "condition_type": "COUNTRY", "conditional": "EQUAL", "values": ["MX"] }
],
"route": {
"start_split": [
{ "index": 1, "percentage": 45 },
{ "index": 2, "percentage": 45 },
{ "index": 3, "percentage": 10 }
],
"steps": [
{
"index": 1,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{ "status": "DECLINED", "next_split": [ { "index": 2, "percentage": 70 }, { "index": 3, "percentage": 30 } ] }
]
},
{ "index": 2, "provider_id": "STRIPE", "connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e" },
{ "index": 3, "provider_id": "DLOCAL", "connection_id": "c3d5e6f7-2b3c-4d5e-8f6a-7b8c9d0e1f2a" }
]
}
}
]
}'
{
"id": "8f2c1d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
"payment_method": "CARD",
"name": "Card routing — Stripe primary, Adyen fallback",
"default_route": {
"steps": [
{
"index": 1,
"provider_id": "STRIPE",
"connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
"output": [
{ "status": "DECLINE_GROUP", "group_id": 1044, "group_name": "Soft declines",
"decline_types": ["DECLINED_BY_BANK", "RESTRICTED_BY_BANK"], "next": 2, "retry": true },
{ "status": "MAC_CODE_GROUP", "group_id": 4542, "group_name": "Do not retry",
"decline_types": ["NO_RETRY_POLICY", "NO_RETRY_SECURITY"], "retry": false },
{ "status": "DECLINED", "next": 2, "retry": false },
{ "status": "INTERNAL_ERROR", "next": 2, "retry": false }
]
},
{ "index": 2, "provider_id": "ADYEN", "connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "output": [{ "status": "APPROVED", "next": null, "decline_types": null, "retry": false }, { "status": "INTERNAL_ERROR", "next": null, "decline_types": null, "retry": false }] }
]
},
"condition_sets": [
{
"sort_number": 1,
"name": "Reject foreign-issued cards",
"conditions": [
{ "condition_type": "CARD_ISSUER_COUNTRY", "conditional": "NOT_ONE_OF", "values": ["BR"] }
],
"route": { "steps": [ { "index": 1, "action": "CANCEL", "output": [] } ] }
},
{
"sort_number": 2,
"name": "Brazil — BRL 300 to 600 via Adyen, capture after 5 minutes",
"conditions": [
{ "condition_type": "COUNTRY", "conditional": "EQUAL", "values": ["BR"] },
{ "condition_type": "AMOUNT", "conditional": "BETWEEN", "values": ["300.00", "600.00"], "currency": "BRL" }
],
"route": {
"steps": [
{ "index": 1, "provider_id": "ADYEN", "connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{ "status": "APPROVED", "next": 2, "retry": false },
{ "status": "SUCCEEDED_GROUP", "group_id": 430, "group_name": "Pending review", "retry": false }
] },
{ "index": 2, "action": "CAPTURE", "action_delay": "PT5M", "output": [] }
]
}
},
{ "sort_number": 3, "name": "Mexico — 45/45/10 between Adyen, Stripe and dLocal", "conditions": ["..."], "route": { "steps": ["..."] } }
],
"created_at": "2026-05-12T14:30:00Z",
"updated_at": "2026-05-12T14:30:00Z"
}
{
"code": "INVALID_ROUTE_CONFIGURATION",
"messages": ["step index=2 with action=CAPTURE must be reached only from an APPROVED output of a provider step"]
}
{
"code": "INVALID_ROUTE_CONFIGURATION",
"messages": ["output.group_id=99 not found for account"]
}
{
"code": "ROUTING_ALREADY_EXISTS",
"messages": ["A routing for payment_method 'CARD' already exists for this account."]
}
Errors
| HTTP | code |
|---|---|
400 | INVALID_PARAMETERSA field is missing or has an invalid value: a step with neither provider_id nor action, a status or action outside their enums, an action_delay on a step that is not CAPTURE, a malformed group_id. messages names the offending field. |
400 | INVALID_FORMATA field has the wrong type or format: time_period_start_time / time_period_end_time not HH:mm:ss, a date in values of a TIME_PERIOD condition not ISO-8601, time_period_repeat_amount or sort_number not an integer, retry not a boolean. messages names the field. |
400 | INVALID_ROUTE_CONFIGURATIONRoute rule violation: non-contiguous step indexes, a next or split branch to a missing step, a split that does not sum to 100 or leaves a step unreachable, a CAPTURE or HOLD_FOR_REVIEW step not reached only from APPROVED, an action_delay under 1 minute or above 7 days, retry on a status that does not support it, a group_id that is unknown, of another account or of the wrong kind, decline_types that do not match the group, a condition that breaks a rule of its condition_type, or a connection_id not found for the account and provider. messages explains which rule. |
400 | INVALID_VOLUME_LIMIT_CURRENCY, INVALID_VOLUME_LIMIT_PERIOD, UNSUPPORTED_VOLUME_LIMIT_TIMEZONEA VOLUME_PAYMENTS_LIMIT condition with an invalid currency, period or timezone. See Volume and count limits. |
400 | INVALID_PROVIDER_IDprovider_id has an invalid format. |
409 | ROUTING_ALREADY_EXISTSA routing already exists for this (account, payment_method). Use PATCH to update it. |
401 | NOT_AUTHENTICATEDMissing public-api-key or private-secret-key header. |
401 | INVALID_CREDENTIALSWrong key pair, or a Dashboard Customized API key was used. Use an account key or organization key instead. |
Authorizations
Headers
Body
application/json
Example:
"7825fc5e-e50a-4248-9ae8-5d3786afb0be"
Example:
"CARD"
Example:
"Card routing"
Show child attributes
Show child attributes
Optional. Ordered by sort_number, first matching set wins.
Show child attributes
Show child attributes
Response
Created
Example:
"8f2c1d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
Example:
"acc-uuid"
Example:
"CARD"
Example:
"Card routing"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Example:
"2026-05-12T14:30:00Z"
Example:
"2026-05-12T14:30:00Z"
Was this page helpful?
⌘I
Create a Routing
curl --request POST \
--url https://api-sandbox.y.uno/v1/routing \
--header 'Content-Type: application/json' \
--header 'PRIVATE-SECRET-KEY: <api-key>' \
--header 'PUBLIC-API-KEY: <api-key>' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--data '
{
"account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
"payment_method": "GOOGLE_PAY",
"name": "Google Pay routing",
"default_route": {
"steps": [
{
"index": 1,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{
"status": "APPROVED",
"next": 3
},
{
"status": "DECLINED",
"retry": false,
"next_split": [
{
"index": 2,
"percentage": 70
},
{
"index": 4,
"percentage": 30
}
]
}
]
},
{
"index": 2,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{
"status": "APPROVED",
"next": 3
}
]
},
{
"index": 3,
"action": "CAPTURE",
"action_delay": "PT5M"
},
{
"index": 4,
"action": "CANCEL"
}
]
},
"condition_sets": [
{
"sort_number": 1,
"name": "US & Canada",
"conditions": [
{
"condition_type": "COUNTRY",
"conditional": "ONE_OF",
"values": [
"US",
"CA"
]
}
],
"route": {
"steps": [
{
"index": 1,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
}
]
}
}
]
}
'import requests
url = "https://api-sandbox.y.uno/v1/routing"
payload = {
"account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
"payment_method": "GOOGLE_PAY",
"name": "Google Pay routing",
"default_route": { "steps": [
{
"index": 1,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{
"status": "APPROVED",
"next": 3
},
{
"status": "DECLINED",
"retry": False,
"next_split": [
{
"index": 2,
"percentage": 70
},
{
"index": 4,
"percentage": 30
}
]
}
]
},
{
"index": 2,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
"output": [
{
"status": "APPROVED",
"next": 3
}
]
},
{
"index": 3,
"action": "CAPTURE",
"action_delay": "PT5M"
},
{
"index": 4,
"action": "CANCEL"
}
] },
"condition_sets": [
{
"sort_number": 1,
"name": "US & Canada",
"conditions": [
{
"condition_type": "COUNTRY",
"conditional": "ONE_OF",
"values": ["US", "CA"]
}
],
"route": { "steps": [
{
"index": 1,
"provider_id": "ADYEN",
"connection_id": "b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
}
] }
}
]
}
headers = {
"X-Idempotency-Key": "<x-idempotency-key>",
"PUBLIC-API-KEY": "<api-key>",
"PRIVATE-SECRET-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Idempotency-Key': '<x-idempotency-key>',
'PUBLIC-API-KEY': '<api-key>',
'PRIVATE-SECRET-KEY': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
account_id: '7825fc5e-e50a-4248-9ae8-5d3786afb0be',
payment_method: 'GOOGLE_PAY',
name: 'Google Pay routing',
default_route: {
steps: [
{
index: 1,
provider_id: 'ADYEN',
connection_id: 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f',
output: [
{status: 'APPROVED', next: 3},
{
status: 'DECLINED',
retry: false,
next_split: [{index: 2, percentage: 70}, {index: 4, percentage: 30}]
}
]
},
{
index: 2,
provider_id: 'ADYEN',
connection_id: 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f',
output: [{status: 'APPROVED', next: 3}]
},
{index: 3, action: 'CAPTURE', action_delay: 'PT5M'},
{index: 4, action: 'CANCEL'}
]
},
condition_sets: [
{
sort_number: 1,
name: 'US & Canada',
conditions: [{condition_type: 'COUNTRY', conditional: 'ONE_OF', values: ['US', 'CA']}],
route: {
steps: [
{
index: 1,
provider_id: 'ADYEN',
connection_id: 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f'
}
]
}
}
]
})
};
fetch('https://api-sandbox.y.uno/v1/routing', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.y.uno/v1/routing",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'account_id' => '7825fc5e-e50a-4248-9ae8-5d3786afb0be',
'payment_method' => 'GOOGLE_PAY',
'name' => 'Google Pay routing',
'default_route' => [
'steps' => [
[
'index' => 1,
'provider_id' => 'ADYEN',
'connection_id' => 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f',
'output' => [
[
'status' => 'APPROVED',
'next' => 3
],
[
'status' => 'DECLINED',
'retry' => false,
'next_split' => [
[
'index' => 2,
'percentage' => 70
],
[
'index' => 4,
'percentage' => 30
]
]
]
]
],
[
'index' => 2,
'provider_id' => 'ADYEN',
'connection_id' => 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f',
'output' => [
[
'status' => 'APPROVED',
'next' => 3
]
]
],
[
'index' => 3,
'action' => 'CAPTURE',
'action_delay' => 'PT5M'
],
[
'index' => 4,
'action' => 'CANCEL'
]
]
],
'condition_sets' => [
[
'sort_number' => 1,
'name' => 'US & Canada',
'conditions' => [
[
'condition_type' => 'COUNTRY',
'conditional' => 'ONE_OF',
'values' => [
'US',
'CA'
]
]
],
'route' => [
'steps' => [
[
'index' => 1,
'provider_id' => 'ADYEN',
'connection_id' => 'b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"PRIVATE-SECRET-KEY: <api-key>",
"PUBLIC-API-KEY: <api-key>",
"X-Idempotency-Key: <x-idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.y.uno/v1/routing"
payload := strings.NewReader("{\n \"account_id\": \"7825fc5e-e50a-4248-9ae8-5d3786afb0be\",\n \"payment_method\": \"GOOGLE_PAY\",\n \"name\": \"Google Pay routing\",\n \"default_route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n },\n {\n \"status\": \"DECLINED\",\n \"retry\": false,\n \"next_split\": [\n {\n \"index\": 2,\n \"percentage\": 70\n },\n {\n \"index\": 4,\n \"percentage\": 30\n }\n ]\n }\n ]\n },\n {\n \"index\": 2,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n }\n ]\n },\n {\n \"index\": 3,\n \"action\": \"CAPTURE\",\n \"action_delay\": \"PT5M\"\n },\n {\n \"index\": 4,\n \"action\": \"CANCEL\"\n }\n ]\n },\n \"condition_sets\": [\n {\n \"sort_number\": 1,\n \"name\": \"US & Canada\",\n \"conditions\": [\n {\n \"condition_type\": \"COUNTRY\",\n \"conditional\": \"ONE_OF\",\n \"values\": [\n \"US\",\n \"CA\"\n ]\n }\n ],\n \"route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n }\n ]\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
req.Header.Add("PUBLIC-API-KEY", "<api-key>")
req.Header.Add("PRIVATE-SECRET-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.y.uno/v1/routing")
.header("X-Idempotency-Key", "<x-idempotency-key>")
.header("PUBLIC-API-KEY", "<api-key>")
.header("PRIVATE-SECRET-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"account_id\": \"7825fc5e-e50a-4248-9ae8-5d3786afb0be\",\n \"payment_method\": \"GOOGLE_PAY\",\n \"name\": \"Google Pay routing\",\n \"default_route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n },\n {\n \"status\": \"DECLINED\",\n \"retry\": false,\n \"next_split\": [\n {\n \"index\": 2,\n \"percentage\": 70\n },\n {\n \"index\": 4,\n \"percentage\": 30\n }\n ]\n }\n ]\n },\n {\n \"index\": 2,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n }\n ]\n },\n {\n \"index\": 3,\n \"action\": \"CAPTURE\",\n \"action_delay\": \"PT5M\"\n },\n {\n \"index\": 4,\n \"action\": \"CANCEL\"\n }\n ]\n },\n \"condition_sets\": [\n {\n \"sort_number\": 1,\n \"name\": \"US & Canada\",\n \"conditions\": [\n {\n \"condition_type\": \"COUNTRY\",\n \"conditional\": \"ONE_OF\",\n \"values\": [\n \"US\",\n \"CA\"\n ]\n }\n ],\n \"route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n }\n ]\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.y.uno/v1/routing")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["PUBLIC-API-KEY"] = '<api-key>'
request["PRIVATE-SECRET-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"account_id\": \"7825fc5e-e50a-4248-9ae8-5d3786afb0be\",\n \"payment_method\": \"GOOGLE_PAY\",\n \"name\": \"Google Pay routing\",\n \"default_route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n },\n {\n \"status\": \"DECLINED\",\n \"retry\": false,\n \"next_split\": [\n {\n \"index\": 2,\n \"percentage\": 70\n },\n {\n \"index\": 4,\n \"percentage\": 30\n }\n ]\n }\n ]\n },\n {\n \"index\": 2,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\",\n \"output\": [\n {\n \"status\": \"APPROVED\",\n \"next\": 3\n }\n ]\n },\n {\n \"index\": 3,\n \"action\": \"CAPTURE\",\n \"action_delay\": \"PT5M\"\n },\n {\n \"index\": 4,\n \"action\": \"CANCEL\"\n }\n ]\n },\n \"condition_sets\": [\n {\n \"sort_number\": 1,\n \"name\": \"US & Canada\",\n \"conditions\": [\n {\n \"condition_type\": \"COUNTRY\",\n \"conditional\": \"ONE_OF\",\n \"values\": [\n \"US\",\n \"CA\"\n ]\n }\n ],\n \"route\": {\n \"steps\": [\n {\n \"index\": 1,\n \"provider_id\": \"ADYEN\",\n \"connection_id\": \"b2c4d5e6-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n }\n ]\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "8f2c1d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
"account_id": "acc-uuid",
"payment_method": "CARD",
"name": "Card routing",
"default_route": {
"start_split": [
{
"index": 1,
"percentage": 45
}
],
"steps": [
{
"index": 1,
"provider_id": "STRIPE",
"connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
"provider_type": "PAYMENT",
"action": "CANCEL",
"action_delay": "PT5M",
"output": [
{
"status": "DECLINED",
"decline_types": [
"<string>"
],
"group_id": 1044,
"group_name": "Soft declines",
"retry": false,
"next": 2,
"next_split": [
{
"index": 2,
"percentage": 70
}
]
}
],
"fraud": {
"rules": "rule-a,rule-b",
"blocklists": "<string>",
"allowlists": "<string>",
"reviewlists": "<string>",
"preset": "<string>",
"report_only": true
},
"smart_routing": {
"type": "LATENCY",
"providers": [
{
"provider_id": "ADYEN",
"connection_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"network_token_on": true
}
],
"no_retry_decline_types": [
"<string>"
],
"no_retry_failure_causes": [
"<string>"
]
}
}
]
},
"condition_sets": [
{
"sort_number": 1,
"name": "High Value US",
"description": "<string>",
"conditions": [
{
"condition_type": "COUNTRY",
"conditional": "ONE_OF",
"values": [
"US",
"CA"
],
"key": "<string>",
"currency": "USD",
"time_period_repeat_amount": 1,
"time_period_repeat_frequency": "DAILY",
"time_period_repetition_days": [
"MONDAY"
],
"time_period_start_time": "09:00:00",
"time_period_end_time": "18:00:00",
"timezone": "-03:00",
"limit_by": "PAYMENTS",
"payments_count": "ALL"
}
],
"route": {}
}
],
"created_at": "2026-05-12T14:30:00Z",
"updated_at": "2026-05-12T14:30:00Z"
}{
"code": "INVALID_ROUTE_CONFIGURATION",
"messages": [
"step index=2 with action=CAPTURE must be reached only from an APPROVED output of a provider step"
]
}{
"code": "NOT_AUTHENTICATED",
"messages": [
"Not authenticated"
]
}{
"code": "ROUTING_ALREADY_EXISTS",
"messages": [
"A routing already exists for this payment method"
]
}