Skip to main content
POST
/
connections
Create a Connection
curl --request POST \
  --url https://api-sandbox.y.uno/v1/connections \
  --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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchant_connection_id": "adyen-us-prod-001",
  "provider_id": "ADYEN",
  "flow_type": "PAYIN",
  "payment_methods": [
    "CARD",
    "GOOGLE_PAY"
  ],
  "params": [
    {
      "param_id": "<string>",
      "value": "<string>"
    }
  ]
}
'
{
  "connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
  "merchant_connection_id": "stripe-us-prod-001",
  "provider_id": "STRIPE",
  "status": "ACTIVE",
  "flow_type": "PAYIN",
  "payment_methods": [
    "CARD",
    "GOOGLE_PAY",
    "APPLE_PAY"
  ],
  "params": [
    {}
  ],
  "costs": [
    {}
  ],
  "created_at": "2026-05-12T10:24:00Z",
  "updated_at": "2026-05-12T10:24:00Z"
}
Creates a connection in ACTIVE status from credentials and configuration you fill in based on the provider’s catalog. The response includes the connection_id you’ll use to reference this connection from routing rules.

​
Headers

​
X-Idempotency-Key
string
required
UUID, 24-hour scope. Re-sending the same key + body returns the cached response; same key with a different body returns a 409.

​
Body

​
account_id
string
required
UUID of the account under which this connection will be created.
​
merchant_connection_id
string
required
Your label for this connection. Must be unique within the account. Free-form (e.g., "adyen-us-prod-001", "stripe-eu-test").
​
provider_id
string
required
Yuno provider identifier (e.g., "STRIPE", "ADYEN"). Must exist in the catalog.
​
flow_type
enum
required
Must be "PAYIN".
​
payment_methods
string[]
required
Subset of the provider’s payment_method_type[] (from the catalog).
​
params
object[]
required
One {param_id, value} pair per parameter you’re supplying. Flat array — even nested catalog params are submitted at the top level; Yuno resolves the hierarchy from the catalog tree.Required params (where the catalog has optional: false) must be present and non-empty. Activating a boolean parent ("value": true) makes its optional: false children required.
​
costs
object[]
required
Per-connection cost configuration. currency must be one supported by the provider.

​
Response

​
connection_id
string
Unique identifier for the connection. Save this value to reference it from routing rules.
​
merchant_connection_id
string
Your internal label for this connection.
​
provider_id
string
The provider this connection belongs to (e.g., ADYEN).
​
status
string
Current status (always ACTIVE on create).
​
flow_type
string
Always PAYIN.
​
payment_methods
string[]
List of supported payment methods.
​
params
object[]
Echoed parameters. Sensitive values are masked as ***.
​
costs
object[]
Cost configuration for the connection.
​
created_at
string
ISO 8601 timestamp.
​
updated_at
string
ISO 8601 timestamp.
curl -X POST 'https://api.y.uno/v1/connections' \
  -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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchant_connection_id": "stripe-us-prod-001",
    "provider_id": "STRIPE",
    "flow_type": "PAYIN",
    "payment_methods": ["CARD", "GOOGLE_PAY", "APPLE_PAY"],
    "params": [
      { "param_id": "API_KEY",           "value": "sk_live_..." },
      { "param_id": "PUBLISHABLE_KEY",   "value": "pk_live_..." },
      { "param_id": "INTEGRATION_TYPE",  "value": "PAYMENT_INTENTS" },
      { "param_id": "3DS_ENABLED",       "value": true },
      { "param_id": "ORIGIN_URL",        "value": "https://checkout.acme.com" }
    ],
    "costs": [
      {
        "sort_number": 1,
        "cost_name": "Transaction Fee",
        "currency": "USD",
        "cost_values": {
          "successful":   { "fixed_fee": 0.30, "percentage": 2.9 },
          "unsuccessful": { "fixed_fee": 0.0,  "percentage": 0.0 }
        }
      }
    ]
  }'
Secret handling: any param marked secret: true in the catalog is returned as "value": "***". Your submitted secret is stored encrypted and never echoed back.

​
Errors

HTTPcodeWhen
400PROVIDER_NOT_FOUNDUnknown provider_id.
400MISSING_REQUIRED_PARAMA required param is missing. details.param_id names which one.
400UNSUPPORTED_PAYMENT_METHODpayment_methods contains a method the provider doesn’t support.
400UNSUPPORTED_CURRENCYA costs[].currency isn’t in the provider’s supported list.
400INVALID_PROVIDER_CREDENTIALSThe credentials failed Yuno’s pre-flight check against the provider. details.provider_message echoes the provider’s reason.
409CONNECTION_MERCHANT_ID_CONFLICTmerchant_connection_id already exists in this account.
403INSUFFICIENT_SCOPEAPI key missing connections:write.

Authorizations

​
PUBLIC-API-KEY
string
header
default:<Your PUBLIC-API-KEY>
required
​
PRIVATE-SECRET-KEY
string
header
default:<Your PRIVATE-SECRET-KEY>
required

Headers

​
X-Idempotency-Key
string<uuid>
required

Body

application/json
​
account_id
string<uuid>
required
Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
merchant_connection_id
string
required
Example:

"adyen-us-prod-001"

​
provider_id
string
required
Example:

"ADYEN"

​
flow_type
string
required
Example:

"PAYIN"

​
payment_methods
string[]
required
Example:
["CARD", "GOOGLE_PAY"]
​
params
object[]
required

Response

Created

​
connection_id
string
Example:

"f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e"

​
merchant_connection_id
string
Example:

"stripe-us-prod-001"

​
provider_id
string
Example:

"STRIPE"

​
status
string
Example:

"ACTIVE"

​
flow_type
string
Example:

"PAYIN"

​
payment_methods
string[]
Example:
["CARD", "GOOGLE_PAY", "APPLE_PAY"]
​
params
object[]
​
costs
object[]
​
created_at
string<date-time>
Example:

"2026-05-12T10:24:00Z"

​
updated_at
string<date-time>
Example:

"2026-05-12T10:24:00Z"