> ## Documentation Index
> Fetch the complete documentation index at: https://yuno-3979e326-2026-05-13-universal-sdk-proposal.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Connection

> Creates a connection in ACTIVE status from credentials and configuration you fill in based on the provider's catalog.

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

<ParamField header="X-Idempotency-Key" type="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`.
</ParamField>

### Body

<ParamField body="merchant_connection_id" type="string" required>
  Your label for this connection. Must be unique within the account. Free-form (e.g., `"adyen-us-prod-001"`, `"stripe-eu-test"`).
</ParamField>

<ParamField body="provider_id" type="string" required>
  Yuno provider identifier (e.g., `"STRIPE"`, `"ADYEN"`). Must exist in the catalog.
</ParamField>

<ParamField body="flow_type" type="enum" required>
  Must be `"PAYIN"`.
</ParamField>

<ParamField body="payment_methods" type="string[]" required>
  Subset of the provider's `payment_method_type[]` (from the catalog).
</ParamField>

<ParamField body="params" type="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.

  <Expandable title="item">
    <ParamField body="param_id" type="string" required>
      The exact `param_id` from the catalog. Casing matters.
    </ParamField>

    <ParamField body="value" type="string | boolean | number | array" required>
      Match the `field_type` from the catalog. Numerics are submitted as JSON numbers (or strings if the catalog says `field_type: "string"`). For `field_type: "array"`, submit a JSON array.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="costs" type="object[]" required>
  Per-connection cost configuration. `currency` must be one supported by the provider.

  <Expandable title="item">
    <ParamField body="sort_number" type="integer">
      Order of priority for the cost entry.
    </ParamField>

    <ParamField body="cost_name" type="string">
      Label for the cost entry.
    </ParamField>

    <ParamField body="currency" type="string">
      ISO 4217 currency code.
    </ParamField>

    <ParamField body="cost_values" type="object">
      <Expandable title="successful | unsuccessful">
        <ParamField body="fixed_fee" type="number">
          Fixed fee amount.
        </ParamField>

        <ParamField body="percentage" type="number">
          Percentage fee.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="connection_id" type="string">
  Unique identifier for the connection. **Save this value** to reference it from routing rules.
</ResponseField>

<ResponseField name="status" type="string">
  Current status (always `ACTIVE` on create).
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
       --url https://api.y.uno/v1/connections \
       --header 'Content-Type: application/json' \
       --header 'X-Idempotency-Key: <UUID>' \
       --header 'private-secret-key: <YOUR_SECRET_KEY>' \
       --header 'public-api-key: <YOUR_PUBLIC_KEY>' \
       --data '
  {
    "merchant_connection_id": "adyen-us-prod-001",
    "provider_id": "ADYEN",
    "flow_type": "PAYIN",
    "payment_methods": ["CARD", "GOOGLE_PAY", "IDEAL"],
    "params": [
      { "param_id": "merchantAccount",        "value": "ACME_LIVE" },
      { "param_id": "x-api-key",              "value": "AQEx…W4w==" }
    ],
    "costs": [
      {
        "sort_number": 1,
        "cost_name": "Transaction Fee",
        "currency": "USD",
        "cost_values": {
          "successful":   { "fixed_fee": 0.12, "percentage": 1.2 },
          "unsuccessful": { "fixed_fee": 0.0,  "percentage": 0.0 }
        }
      }
    ]
  }
  '
  ```

  ```json Response theme={null}
  {
    "connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
    "merchant_connection_id": "adyen-us-prod-001",
    "provider_id": "ADYEN",
    "status": "ACTIVE",
    "flow_type": "PAYIN",
    "payment_methods": ["CARD", "GOOGLE_PAY", "IDEAL"],
    "params": [
      { "param_id": "merchantAccount",        "value": "ACME_LIVE" },
      { "param_id": "x-api-key",              "value": "***" }
    ],
    "created_at": "2026-05-12T10:24:00Z",
    "updated_at": "2026-05-12T10:24:00Z"
  }
  ```
</CodeGroup>

<Note>
  **Secret handling:** any param marked `secret: true` in the catalog is returned as `"value": "***"`. Your submitted secret is stored encrypted and never echoed back.
</Note>

### Errors

| HTTP  | `code`                            | When                                                                                                                          |
| ----- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `400` | `PROVIDER_NOT_FOUND`              | Unknown `provider_id`.                                                                                                        |
| `400` | `MISSING_REQUIRED_PARAM`          | A required param is missing. `details.param_id` names which one.                                                              |
| `400` | `UNSUPPORTED_PAYMENT_METHOD`      | `payment_methods` contains a method the provider doesn't support.                                                             |
| `400` | `UNSUPPORTED_CURRENCY`            | A `costs[].currency` isn't in the provider's supported list.                                                                  |
| `400` | `INVALID_PROVIDER_CREDENTIALS`    | The credentials failed Yuno's pre-flight check against the provider. `details.provider_message` echoes the provider's reason. |
| `409` | `CONNECTION_MERCHANT_ID_CONFLICT` | `merchant_connection_id` already exists in this account.                                                                      |
| `403` | `INSUFFICIENT_SCOPE`              | API key missing `connections:write`.                                                                                          |


## OpenAPI

````yaml openapi/organizations/connections/create-connection.json POST /connections
openapi: 3.1.0
info:
  title: Connections API - Create
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
security:
  - sec0: []
    sec1: []
paths:
  /connections:
    post:
      summary: Create a Connection
      description: Creates a connection in ACTIVE status.
      operationId: create-connection
      parameters:
        - name: X-Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - merchant_connection_id
                - provider_id
                - flow_type
                - payment_methods
                - params
              properties:
                merchant_connection_id:
                  type: string
                  example: adyen-us-prod-001
                provider_id:
                  type: string
                  example: ADYEN
                flow_type:
                  type: string
                  example: PAYIN
                payment_methods:
                  type: array
                  items:
                    type: string
                  example:
                    - CARD
                    - GOOGLE_PAY
                params:
                  type: array
                  items:
                    type: object
                    properties:
                      param_id:
                        type: string
                      value:
                        type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  connection_id:
                    type: string
                  status:
                    type: string
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: PUBLIC-API-KEY
      x-default: <Your PUBLIC-API-KEY>
    sec1:
      type: apiKey
      in: header
      name: PRIVATE-SECRET-KEY
      x-default: <Your PRIVATE-SECRET-KEY>

````