Get a Routing Recommendation - Yuno API Documentation

POST

routing

recommendations

Get a Routing Recommendation

curl --request POST \
  --url https://api-sandbox.y.uno/v1/routing/recommendations \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-SECRET-KEY: <api-key>' \
  --header 'PUBLIC-API-KEY: <api-key>' \
  --data '
{
  "account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
  "merchant_order_id": "order_45678",
  "payment": {
    "amount": {
      "currency": "USD",
      "value": 99
    },
    "country": "US",
    "payment_method": {
      "type": "CARD"
    }
  },
  "candidates": [
    {
      "provider_id": "ADYEN",
      "merchant_connection_id": "acct-adyen-us-1"
    },
    {
      "provider_id": "STRIPE"
    },
    {
      "provider_id": "DLOCAL"
    }
  ],
  "optimize_for": "APPROVAL_RATE"
}
'

import requests

url = "https://api-sandbox.y.uno/v1/routing/recommendations"

payload = {
    "account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
    "merchant_order_id": "order_45678",
    "payment": {
        "amount": {
            "currency": "USD",
            "value": 99
        },
        "country": "US",
        "payment_method": { "type": "CARD" }
    },
    "candidates": [{
            "provider_id": "ADYEN",
            "merchant_connection_id": "acct-adyen-us-1"
        }, { "provider_id": "STRIPE" }, { "provider_id": "DLOCAL" }],
    "optimize_for": "APPROVAL_RATE"
}
headers = {
    "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: {
    'PUBLIC-API-KEY': '<api-key>',
    'PRIVATE-SECRET-KEY': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    account_id: '7825fc5e-e50a-4248-9ae8-5d3786afb0be',
    merchant_order_id: 'order_45678',
    payment: {
      amount: {currency: 'USD', value: 99},
      country: 'US',
      payment_method: {type: 'CARD'}
    },
    candidates: [
      {provider_id: 'ADYEN', merchant_connection_id: 'acct-adyen-us-1'},
      {provider_id: 'STRIPE'},
      {provider_id: 'DLOCAL'}
    ],
    optimize_for: 'APPROVAL_RATE'
  })
};

fetch('https://api-sandbox.y.uno/v1/routing/recommendations', 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/recommendations",
  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',
    'merchant_order_id' => 'order_45678',
    'payment' => [
        'amount' => [
                'currency' => 'USD',
                'value' => 99
        ],
        'country' => 'US',
        'payment_method' => [
                'type' => 'CARD'
        ]
    ],
    'candidates' => [
        [
                'provider_id' => 'ADYEN',
                'merchant_connection_id' => 'acct-adyen-us-1'
        ],
        [
                'provider_id' => 'STRIPE'
        ],
        [
                'provider_id' => 'DLOCAL'
        ]
    ],
    'optimize_for' => 'APPROVAL_RATE'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "PRIVATE-SECRET-KEY: <api-key>",
    "PUBLIC-API-KEY: <api-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/recommendations"

	payload := strings.NewReader("{\n  \"account_id\": \"7825fc5e-e50a-4248-9ae8-5d3786afb0be\",\n  \"merchant_order_id\": \"order_45678\",\n  \"payment\": {\n    \"amount\": {\n      \"currency\": \"USD\",\n      \"value\": 99\n    },\n    \"country\": \"US\",\n    \"payment_method\": {\n      \"type\": \"CARD\"\n    }\n  },\n  \"candidates\": [\n    {\n      \"provider_id\": \"ADYEN\",\n      \"merchant_connection_id\": \"acct-adyen-us-1\"\n    },\n    {\n      \"provider_id\": \"STRIPE\"\n    },\n    {\n      \"provider_id\": \"DLOCAL\"\n    }\n  ],\n  \"optimize_for\": \"APPROVAL_RATE\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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/recommendations")
  .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  \"merchant_order_id\": \"order_45678\",\n  \"payment\": {\n    \"amount\": {\n      \"currency\": \"USD\",\n      \"value\": 99\n    },\n    \"country\": \"US\",\n    \"payment_method\": {\n      \"type\": \"CARD\"\n    }\n  },\n  \"candidates\": [\n    {\n      \"provider_id\": \"ADYEN\",\n      \"merchant_connection_id\": \"acct-adyen-us-1\"\n    },\n    {\n      \"provider_id\": \"STRIPE\"\n    },\n    {\n      \"provider_id\": \"DLOCAL\"\n    }\n  ],\n  \"optimize_for\": \"APPROVAL_RATE\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v1/routing/recommendations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
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  \"merchant_order_id\": \"order_45678\",\n  \"payment\": {\n    \"amount\": {\n      \"currency\": \"USD\",\n      \"value\": 99\n    },\n    \"country\": \"US\",\n    \"payment_method\": {\n      \"type\": \"CARD\"\n    }\n  },\n  \"candidates\": [\n    {\n      \"provider_id\": \"ADYEN\",\n      \"merchant_connection_id\": \"acct-adyen-us-1\"\n    },\n    {\n      \"provider_id\": \"STRIPE\"\n    },\n    {\n      \"provider_id\": \"DLOCAL\"\n    }\n  ],\n  \"optimize_for\": \"APPROVAL_RATE\"\n}"

response = http.request(request)
puts response.read_body

{
  "recommendation_id": "3e37f0c9-e9cd-4d85-9e1a-ec5f09af296d",
  "merchant_order_id": "order_45678",
  "optimized_for": "APPROVAL_RATE",
  "decision_source": "MERCHANT_HISTORY",
  "recommended": {
    "provider_id": "ADYEN",
    "merchant_connection_id": "acct-adyen-us-1"
  },
  "ranking": [
    {
      "provider_id": "ADYEN",
      "merchant_connection_id": "acct-adyen-us-1",
      "approval_rate": 0.9987,
      "avg_latency_ms": 180,
      "sample_size": 767
    }
  ]
}

{
  "code": "INVALID_PARAMETERS",
  "messages": [
    "The field 'candidates' has a value less than allowed."
  ]
}

{
  "code": "INVALID_CREDENTIALS",
  "messages": [
    "Invalid Credentials"
  ]
}

{
  "code": "PRODUCT_NOT_ENABLED",
  "messages": [
    "The Routing Recommendations API is enabled per organization. Contact your Key Account Manager (KAM) to activate it."
  ]
}

{
  "code": "ROUTING_UPSTREAM_ERROR",
  "messages": [
    "routing service unavailable."
  ]
}

This endpoint recommends which of your own provider accounts to route a payment to, based on the outcome history you send Yuno through the Transaction Reporting API. You send the payment context and the candidates you can actually use; Yuno returns the recommended candidate, a full ranking with per-candidate metrics, and a recommendation_id. The transaction itself never passes through Yuno. Yuno recommends; you decide and process.

Enabled per organization — this API requires activation for your organization. Contact your Key Account Manager (KAM) to enable it. Until then every call returns 403 PRODUCT_NOT_ENABLED.

How it works

You report your off-Yuno transaction outcomes through the Transaction Reporting API. Only payments with origin: REPORTED feed the statistics — Yuno-processed traffic is a different population and is deliberately kept out.
Before routing a payment, you call this endpoint with the payment context and your candidate providers.
Yuno computes statistics per candidate — approval rate, average provider latency, sample size — over a rolling 30-day window of your reported payments, segmented by provider, country and payment method (and BIN, when you send it), and returns the ranking ordered by your objective.
You route the payment yourself and report its outcome. If the reported event carries the same merchant_order_id you sent here, Yuno attributes the outcome to this recommendation automatically — closing the loop without you storing recommendation_id.

Only reported payments in a terminal status feed the approval rate: SUCCEEDED counts as approved and SUCCEEDED + DECLINED as decided. Payments in any other status (e.g. ERROR, pending) are ignored for the rate and latency, though they still count toward sample_size.

Request body

string (UUID)

required

The merchant account the recommendation is issued for. Travels in the body; Yuno promotes it to the account header internally. Must belong to the organization of the API credentials.

string

Optional merchant-supplied order reference (max 255). Stored with the issued recommendation as the correlation key for closed-loop attribution.

object

required

The payment context the recommendation is scored against.

Show properties

object

required

Show properties

string

required

ISO 4217 currency code, e.g. USD.

number

required

Transaction amount. Must be ≥ 0.

string

required

ISO 3166-1 alpha-2 country code, e.g. US. Selects the statistics segment.

object

required

Show properties

string

required

E.g. CARD, PIX, WALLET. Selects the statistics segment.

object

Optional. card.bin (numeric) refines the context when available.

enum

Optional. CIT (customer-initiated) or MIT (merchant-initiated).

object[]

required

The providers to rank. Between 2 and 20 items — a recommendation over a single candidate is meaningless.

Show item

string

required

Provider code, e.g. ADYEN, STRIPE, DLOCAL.

string

Optional passthrough for your own bookkeeping — returned exactly as sent, not validated.

enum

default:"APPROVAL_RATE"

The objective the ranking optimizes. APPROVAL_RATE (default), LATENCY, or BALANCED.

Response

string

Unique identifier of the issued recommendation. A fresh id is generated on every call.

string

Echo of the request field, when supplied; null otherwise.

enum

The objective applied to the ranking.

enum

How the ranking was decided — MERCHANT_HISTORY or INSUFFICIENT_DATA (see below).

object

The top of the ranking. Always present.

Show properties

string

The recommended provider code.

string

The candidate’s merchant_connection_id, when it was supplied.

object[]

Every candidate, ordered by the objective.

Show item

string

Provider code.

string

The candidate’s merchant_connection_id, when it was supplied.

number

SUCCEEDED / (SUCCEEDED + DECLINED) over the reported history, 0–1. null when there is no data.

integer

Average authorization latency in milliseconds over SUCCEEDED + DECLINED. null when there is no data.

integer

Total reported payments in the segment over the window, across all statuses — how much history backs this candidate’s metrics.

Reading the response

recommended is always present — even without enough history. You never need a special branch: decision_source tells you how much to trust it.
decision_source: MERCHANT_HISTORY — at least one candidate reached the minimum sample; the ranking reflects real statistics over your reported payments.
decision_source: INSUFFICIENT_DATA — no candidate reached the minimum sample of recent reported events. The full ranking still comes back, and the recommendation falls back to the best available data, or to request order as a last resort. Read each candidate’s sample_size to see how much history backs it before relying on the order.
sample_size is the honesty of the recommendation. A high approval rate over 12 events is not the same signal as one over 12,000.
The full ranking always comes back, ordered by your objective. If the recommended candidate declines, take the next entry — cascade retry without a second call.

Choosing an objective

optimize_for orders the ranking: APPROVAL_RATE (default), LATENCY, or BALANCED (a weighted blend of both). There is no cost objective yet — the Reporting API does not collect fees, and Yuno does not rank on data it does not have.

Candidates are your constraint layer

The recommendation is always one of the candidates you send — Yuno never proposes a provider you did not list. Send only the providers this payment is genuinely allowed to use (eligibility, contracts, committed volumes), and the recommendation respects those constraints by construction.

Retries

There is no idempotency header on this endpoint, and none is needed: each call computes a fresh recommendation with a new recommendation_id, and requesting a recommendation changes no state. Retrying after a network failure is always safe.

Examples

curl -X POST 'https://api-sandbox.y.uno/v1/routing/recommendations' \
  -H 'public-api-key: <YOUR_PUBLIC_KEY>' \
  -H 'private-secret-key: <YOUR_SECRET_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
    "merchant_order_id": "order_45678",
    "payment": {
      "amount": { "currency": "USD", "value": 99.00 },
      "country": "US",
      "payment_method": { "type": "CARD" }
    },
    "candidates": [
      { "provider_id": "ADYEN", "merchant_connection_id": "acct-adyen-us-1" },
      { "provider_id": "STRIPE" },
      { "provider_id": "DLOCAL" }
    ],
    "optimize_for": "APPROVAL_RATE"
  }'

{
  "recommendation_id": "3e37f0c9-e9cd-4d85-9e1a-ec5f09af296d",
  "merchant_order_id": "order_45678",
  "optimized_for": "APPROVAL_RATE",
  "decision_source": "MERCHANT_HISTORY",
  "recommended": { "provider_id": "ADYEN", "merchant_connection_id": "acct-adyen-us-1" },
  "ranking": [
    { "provider_id": "ADYEN",  "merchant_connection_id": "acct-adyen-us-1", "approval_rate": 0.9987, "avg_latency_ms": 180, "sample_size": 767 },
    { "provider_id": "STRIPE", "merchant_connection_id": null, "approval_rate": 0.9167, "avg_latency_ms": 150, "sample_size": 60 },
    { "provider_id": "DLOCAL", "merchant_connection_id": null, "approval_rate": 0.8000, "avg_latency_ms": 210, "sample_size": 60 }
  ]
}

{
  "recommendation_id": "7249c858-1f0f-4654-93e7-ebe34bc5048f",
  "merchant_order_id": "order_45678",
  "optimized_for": "APPROVAL_RATE",
  "decision_source": "INSUFFICIENT_DATA",
  "recommended": { "provider_id": "ADYEN", "merchant_connection_id": null },
  "ranking": [
    { "provider_id": "ADYEN",  "merchant_connection_id": null, "approval_rate": null, "avg_latency_ms": null, "sample_size": 0 },
    { "provider_id": "STRIPE", "merchant_connection_id": null, "approval_rate": null, "avg_latency_ms": null, "sample_size": 0 }
  ]
}

{
  "code": "INVALID_PARAMETERS",
  "messages": ["The field 'candidates' has a value less than allowed."]
}

Errors

Errors return a code and a messages array.

HTTP	`code`	When
`400`	`INVALID_PARAMETERS`	Malformed body, a missing required field, fewer than 2 or more than 20 candidates, a non-ISO `country`/`currency`, or an invalid enum (`optimize_for`, `initiation`).
`400`	`INVALID_ACCOUNT_ID`	`account_id` is malformed or does not belong to your organization.
`401`	`INVALID_CREDENTIALS`	Missing or invalid `PUBLIC-API-KEY` / `PRIVATE-SECRET-KEY` headers.
`403`	`PRODUCT_NOT_ENABLED`	The Routing Recommendations API is not enabled for your organization. Contact your KAM.
`502`	`ROUTING_UPSTREAM_ERROR`	The routing service could not be reached.

Authorizations

PUBLIC-API-KEY

string

header

default:<Your PUBLIC-API-KEY>

required

PRIVATE-SECRET-KEY

string

header

default:<Your PRIVATE-SECRET-KEY>

required

Body

application/json

account_id

string<uuid>

required

Example:

"7825fc5e-e50a-4248-9ae8-5d3786afb0be"

payment

object

required

Show child attributes

candidates

object[]

required

Required array length: 2 - 20 elements

Show child attributes

merchant_order_id

string

Maximum string length: 255

Example:

"order_45678"

optimize_for

enum<string>

default:APPROVAL_RATE

Available options:

APPROVAL_RATE,

LATENCY,

BALANCED

Example:

"APPROVAL_RATE"

Response

recommendation_id

string<uuid>

Example:

"3e37f0c9-e9cd-4d85-9e1a-ec5f09af296d"

merchant_order_id

string | null

Example:

"order_45678"

optimized_for

enum<string>

Available options:

APPROVAL_RATE,

LATENCY,

BALANCED

Example:

"APPROVAL_RATE"

decision_source

enum<string>

Available options:

MERCHANT_HISTORY,

INSUFFICIENT_DATA

Example:

"MERCHANT_HISTORY"

recommended

object

Show child attributes

ranking

object[]

Show child attributes

Get a Routing Recommendation

curl --request POST \
  --url https://api-sandbox.y.uno/v1/routing/recommendations \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-SECRET-KEY: <api-key>' \
  --header 'PUBLIC-API-KEY: <api-key>' \
  --data '
{
  "account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
  "merchant_order_id": "order_45678",
  "payment": {
    "amount": {
      "currency": "USD",
      "value": 99
    },
    "country": "US",
    "payment_method": {
      "type": "CARD"
    }
  },
  "candidates": [
    {
      "provider_id": "ADYEN",
      "merchant_connection_id": "acct-adyen-us-1"
    },
    {
      "provider_id": "STRIPE"
    },
    {
      "provider_id": "DLOCAL"
    }
  ],
  "optimize_for": "APPROVAL_RATE"
}
'

import requests

url = "https://api-sandbox.y.uno/v1/routing/recommendations"

payload = {
    "account_id": "7825fc5e-e50a-4248-9ae8-5d3786afb0be",
    "merchant_order_id": "order_45678",
    "payment": {
        "amount": {
            "currency": "USD",
            "value": 99
        },
        "country": "US",
        "payment_method": { "type": "CARD" }
    },
    "candidates": [{
            "provider_id": "ADYEN",
            "merchant_connection_id": "acct-adyen-us-1"
        }, { "provider_id": "STRIPE" }, { "provider_id": "DLOCAL" }],
    "optimize_for": "APPROVAL_RATE"
}
headers = {
    "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: {
    'PUBLIC-API-KEY': '<api-key>',
    'PRIVATE-SECRET-KEY': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    account_id: '7825fc5e-e50a-4248-9ae8-5d3786afb0be',
    merchant_order_id: 'order_45678',
    payment: {
      amount: {currency: 'USD', value: 99},
      country: 'US',
      payment_method: {type: 'CARD'}
    },
    candidates: [
      {provider_id: 'ADYEN', merchant_connection_id: 'acct-adyen-us-1'},
      {provider_id: 'STRIPE'},
      {provider_id: 'DLOCAL'}
    ],
    optimize_for: 'APPROVAL_RATE'
  })
};

fetch('https://api-sandbox.y.uno/v1/routing/recommendations', 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/recommendations",
  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',
    'merchant_order_id' => 'order_45678',
    'payment' => [
        'amount' => [
                'currency' => 'USD',
                'value' => 99
        ],
        'country' => 'US',
        'payment_method' => [
                'type' => 'CARD'
        ]
    ],
    'candidates' => [
        [
                'provider_id' => 'ADYEN',
                'merchant_connection_id' => 'acct-adyen-us-1'
        ],
        [
                'provider_id' => 'STRIPE'
        ],
        [
                'provider_id' => 'DLOCAL'
        ]
    ],
    'optimize_for' => 'APPROVAL_RATE'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "PRIVATE-SECRET-KEY: <api-key>",
    "PUBLIC-API-KEY: <api-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/recommendations"

	payload := strings.NewReader("{\n  \"account_id\": \"7825fc5e-e50a-4248-9ae8-5d3786afb0be\",\n  \"merchant_order_id\": \"order_45678\",\n  \"payment\": {\n    \"amount\": {\n      \"currency\": \"USD\",\n      \"value\": 99\n    },\n    \"country\": \"US\",\n    \"payment_method\": {\n      \"type\": \"CARD\"\n    }\n  },\n  \"candidates\": [\n    {\n      \"provider_id\": \"ADYEN\",\n      \"merchant_connection_id\": \"acct-adyen-us-1\"\n    },\n    {\n      \"provider_id\": \"STRIPE\"\n    },\n    {\n      \"provider_id\": \"DLOCAL\"\n    }\n  ],\n  \"optimize_for\": \"APPROVAL_RATE\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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/recommendations")
  .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  \"merchant_order_id\": \"order_45678\",\n  \"payment\": {\n    \"amount\": {\n      \"currency\": \"USD\",\n      \"value\": 99\n    },\n    \"country\": \"US\",\n    \"payment_method\": {\n      \"type\": \"CARD\"\n    }\n  },\n  \"candidates\": [\n    {\n      \"provider_id\": \"ADYEN\",\n      \"merchant_connection_id\": \"acct-adyen-us-1\"\n    },\n    {\n      \"provider_id\": \"STRIPE\"\n    },\n    {\n      \"provider_id\": \"DLOCAL\"\n    }\n  ],\n  \"optimize_for\": \"APPROVAL_RATE\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v1/routing/recommendations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
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  \"merchant_order_id\": \"order_45678\",\n  \"payment\": {\n    \"amount\": {\n      \"currency\": \"USD\",\n      \"value\": 99\n    },\n    \"country\": \"US\",\n    \"payment_method\": {\n      \"type\": \"CARD\"\n    }\n  },\n  \"candidates\": [\n    {\n      \"provider_id\": \"ADYEN\",\n      \"merchant_connection_id\": \"acct-adyen-us-1\"\n    },\n    {\n      \"provider_id\": \"STRIPE\"\n    },\n    {\n      \"provider_id\": \"DLOCAL\"\n    }\n  ],\n  \"optimize_for\": \"APPROVAL_RATE\"\n}"

response = http.request(request)
puts response.read_body

{
  "recommendation_id": "3e37f0c9-e9cd-4d85-9e1a-ec5f09af296d",
  "merchant_order_id": "order_45678",
  "optimized_for": "APPROVAL_RATE",
  "decision_source": "MERCHANT_HISTORY",
  "recommended": {
    "provider_id": "ADYEN",
    "merchant_connection_id": "acct-adyen-us-1"
  },
  "ranking": [
    {
      "provider_id": "ADYEN",
      "merchant_connection_id": "acct-adyen-us-1",
      "approval_rate": 0.9987,
      "avg_latency_ms": 180,
      "sample_size": 767
    }
  ]
}

{
  "code": "INVALID_PARAMETERS",
  "messages": [
    "The field 'candidates' has a value less than allowed."
  ]
}

{
  "code": "INVALID_CREDENTIALS",
  "messages": [
    "Invalid Credentials"
  ]
}

{
  "code": "PRODUCT_NOT_ENABLED",
  "messages": [
    "The Routing Recommendations API is enabled per organization. Contact your Key Account Manager (KAM) to activate it."
  ]
}

{
  "code": "ROUTING_UPSTREAM_ERROR",
  "messages": [
    "routing service unavailable."
  ]
}

​How it works

​Request body

​Response

​Reading the response

​Choosing an objective

​Candidates are your constraint layer

​Retries

​Examples

​Errors

Authorizations

Body

Response

How it works

Request body

Response

Reading the response

Choosing an objective

Candidates are your constraint layer

Retries

Examples

Errors