> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Crear una conexión

> Crea una conexión en estado ACTIVE a partir de las credenciales y la configuración que completas según el catálogo del proveedor.

Crea una conexión en estado `ACTIVE` a partir de las credenciales y la configuración que completas según el catálogo del proveedor. La respuesta incluye el `connection_id` que usarás para referenciar esta conexión desde las reglas de enrutamiento.

### Encabezados

**X-account-code** `string` *required*

Código de la cuenta bajo la cual se crea la conexión. La cuenta proviene de este encabezado, no del cuerpo de la solicitud.

**X-Idempotency-Key** `string` *required*

UUID, con alcance de 24 horas. Reenviar la misma clave y el mismo cuerpo devuelve la respuesta en caché; la misma clave con un cuerpo distinto devuelve un `409`.

### Cuerpo

**merchant\_connection\_id** `string` *required*

Tu etiqueta para esta conexión. Debe ser única dentro de la cuenta. Formato libre (por ejemplo, `"adyen-us-prod-001"`, `"stripe-eu-test"`).

**provider\_id** `string` *required*

Identificador del proveedor en Yuno (por ejemplo, `"STRIPE"`, `"ADYEN"`). Debe existir en el catálogo.

**flow\_type** `enum`

Opcional. Por defecto es `"PAYIN"`, el único valor admitido.

**payment\_methods** `string[]`

Opcional. Subconjunto de los `payment_method_type[]` del proveedor (del catálogo).

Omite este campo para habilitar todos los métodos de pago que admite el proveedor. Los métodos de pago que el proveedor agregue más adelante también se agregan a la conexión.

Si lo envías, incluye al menos un método de pago. Un arreglo vacío (`[]`) se rechaza con `400 VALIDATION_ERROR`: omite el campo o envíalo con valores.

**params** `object[]` *required*

Un par `{param_id, value}` por cada parámetro que proporcionas. **Arreglo plano**: incluso los parámetros anidados del catálogo se envían en el nivel superior; Yuno resuelve la jerarquía a partir del árbol del catálogo.

Los parámetros obligatorios (donde el catálogo tiene `optional: false`) deben estar presentes y no vacíos. Activar un padre `boolean` (`"value": true`) hace obligatorios a sus hijos con `optional: false`.

**elemento**

**param\_id** `string` *required*

El `param_id` exacto del catálogo. Las mayúsculas y minúsculas importan.

**value** `string | boolean | number | array` *required*

Debe coincidir con el `field_type` del catálogo. Los valores numéricos se envían como números JSON (o como cadenas si el catálogo indica `field_type: "string"`). Para `field_type: "array"`, envía un arreglo JSON.

**costs** `object[]`

Opcional. Configuración de costos por conexión. Omítela para una conexión sin costos. `currency` debe ser una admitida por el proveedor.

**elemento**

**sort\_number** `integer`

Orden de prioridad de la entrada de costo.

**cost\_name** `string`

Etiqueta de la entrada de costo.

**currency** `string`

Código de moneda ISO 4217.

**cost\_values** `object`

**successful | unsuccessful**

**fixed\_fee** `number`

Monto de la tarifa fija.

**percentage** `number`

Tarifa porcentual.

### Respuesta

**connection\_id** `string`

Identificador único de la conexión. **Guarda este valor** para referenciarla desde las reglas de enrutamiento.

**merchant\_connection\_id** `string`

Tu etiqueta interna para esta conexión.

**provider\_id** `string`

El proveedor al que pertenece esta conexión (por ejemplo, `ADYEN`).

**status** `string`

Estado actual (siempre `ACTIVE` al crear).

**flow\_type** `string`

Siempre `PAYIN`.

**payment\_methods** `string[]`

Lista de métodos de pago admitidos.

**params** `object[]`

Parámetros devueltos como eco. Los valores sensibles se enmascaran como `***`.

**costs** `object[]`

Configuración de costos de la conexión.

**created\_at** `string`

Marca de tiempo ISO 8601.

**updated\_at** `string`

Marca de tiempo ISO 8601.

```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl -X POST 'https://api.y.uno/v1/connections' \
  -H 'public-api-key: <YOUR_PUBLIC_KEY>' \
  -H 'private-secret-key: <YOUR_SECRET_KEY>' \
  -H 'X-account-code: <ACCOUNT_CODE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: <UUID>' \
  -d '{
    "merchant_connection_id": "stripe-us-prod-001",
    "provider_id": "STRIPE",
    "flow_type": "PAYIN",
    "payment_methods": ["CARD"],
    "params": [
      { "param_id": "INTEGRATION_TYPE",             "value": "STRIPE_CHARGES" },
      { "param_id": "SECRET_KEY",                   "value": "sk_live_..." },
      { "param_id": "RADAR_FRAUD_ANALYSIS",         "value": false },
      { "param_id": "SEND_RECEIPT_EMAIL_PARAMETER", "value": false },
      { "param_id": "SETUP_FUTURE_USAGE",           "value": false },
      { "param_id": "ORDER_ID",                     "value": "DEFAULT" }
    ],
    "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 }
        }
      }
    ]
  }'
```

```json 201 Created — Stripe theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "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"],
  "params": [
    { "param_id": "INTEGRATION_TYPE",             "value": "STRIPE_CHARGES" },
    { "param_id": "SECRET_KEY",                   "value": "***" },
    { "param_id": "RADAR_FRAUD_ANALYSIS",         "value": false },
    { "param_id": "SEND_RECEIPT_EMAIL_PARAMETER", "value": false },
    { "param_id": "SETUP_FUTURE_USAGE",           "value": false },
    { "param_id": "ORDER_ID",                     "value": "DEFAULT" }
  ],
  "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 }
      }
    }
  ],
  "created_at": "2026-05-12T10:24:00Z",
  "updated_at": "2026-05-12T10:24:00Z"
}
```

```json 201 Created — Adyen theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "connection_id": "b2c4d5e6-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "merchant_connection_id": "adyen-eu-prod-001",
  "provider_id": "ADYEN",
  "status": "ACTIVE",
  "flow_type": "PAYIN",
  "payment_methods": ["CARD", "GOOGLE_PAY"],
  "params": [
    { "param_id": "merchantAccount",        "value": "ACME_LIVE" },
    { "param_id": "x-api-key",              "value": "***" },
    { "param_id": "transaction-identifier", "value": "MERCHANT_REFERENCE" }
  ],
  "created_at": "2026-05-12T10:31:42Z",
  "updated_at": "2026-05-12T10:31:42Z"
}
```

```json 400 — Missing Param theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "validation_error",
  "code": "MISSING_REQUIRED_PARAM",
  "message": "Required param 'SECRET_KEY' is missing for provider 'STRIPE'",
  "details": { "provider_id": "STRIPE", "param_id": "SECRET_KEY" }
}
```

```json 409 — Conflict theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "conflict",
  "code": "CONNECTION_MERCHANT_ID_CONFLICT",
  "message": "A connection with merchant_connection_id 'stripe-us-prod-001' already exists in this account",
  "details": { "merchant_connection_id": "stripe-us-prod-001" }
}
```

> [!NOTE]
>
> Yuno valida los valores de `param_id`, los parámetros obligatorios y `costs[].currency` contra el catálogo del proveedor. No llama al proveedor para verificar las credenciales, por lo que una clave incorrecta se acepta con `201`.

> [!NOTE]
>
> **Manejo de secretos:** cualquier parámetro marcado como `secret: true` en el catálogo se devuelve como `"value": "***"`. Tu secreto enviado se almacena cifrado y nunca se devuelve.

### Errores

| HTTP | `code` |
| - | - |
| `400` | `PROVIDER_NOT_FOUND` `provider_id` desconocido. |
| `400` | `MISSING_REQUIRED_PARAM` Falta un parámetro obligatorio. `details.param_id` indica cuál. |
| `400` | `UNSUPPORTED_PAYMENT_METHOD` `payment_methods` contiene un método que el proveedor no admite. |
| `400` | `NO_SUPPORTED_PAYMENT_METHODS` Se omitió `payment_methods` y el proveedor no tiene ningún método de pago disponible para el tipo de integración de la conexión. |
| `400` | `VALIDATION_ERROR` El cuerpo no pasó la validación, por ejemplo `payment_methods` enviado como un arreglo vacío. `details` indica el campo. |
| `400` | `UNSUPPORTED_CURRENCY` Un `costs[].currency` no está en la lista de monedas admitidas por el proveedor. |
| `401` | `NOT_AUTHENTICATED` Clave de API ausente o no válida. |
| `409` | `CONNECTION_MERCHANT_ID_CONFLICT` `merchant_connection_id` ya existe en esta cuenta. |


## OpenAPI

````yaml openapi/es/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
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /connections:
    post:
      summary: Crear una conexión
      description: Crea una conexión con estado ACTIVE.
      operationId: create-connection
      parameters:
        - name: X-account-code
          in: header
          required: true
          description: La cuenta propietaria de la conexión.
          schema:
            type: string
        - 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
                - params
              properties:
                merchant_connection_id:
                  type: string
                  example: stripe-us-prod-001
                provider_id:
                  type: string
                  example: STRIPE
                flow_type:
                  type: string
                  description: Opcional. El valor predeterminado es PAYIN.
                  example: PAYIN
                payment_methods:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  description: >-
                    Opcional. Subconjunto de payment_method_type[] del
                    proveedor. Omítelo para habilitar todos los métodos de pago
                    que admite el proveedor, incluidos los que se agreguen más
                    adelante. Si lo envías, debe contener al menos un valor: un
                    arreglo vacío se rechaza con 400 VALIDATION_ERROR.
                  example:
                    - CARD
                params:
                  type: array
                  items:
                    type: object
                    properties:
                      param_id:
                        type: string
                      value:
                        type:
                          - string
                          - boolean
                          - number
                          - array
                costs:
                  type: array
                  description: Opcional. Configuración de costos por conexión.
                  items:
                    type: object
                    properties:
                      sort_number:
                        type: integer
                      cost_name:
                        type: string
                      currency:
                        type: string
                      cost_values:
                        type: object
            example:
              merchant_connection_id: stripe-us-prod-001
              provider_id: STRIPE
              flow_type: PAYIN
              payment_methods:
                - CARD
              params:
                - param_id: INTEGRATION_TYPE
                  value: STRIPE_CHARGES
                - param_id: SECRET_KEY
                  value: sk_live_...
                - param_id: RADAR_FRAUD_ANALYSIS
                  value: false
                - param_id: SEND_RECEIPT_EMAIL_PARAMETER
                  value: false
                - param_id: SETUP_FUTURE_USAGE
                  value: false
                - param_id: ORDER_ID
                  value: DEFAULT
              costs:
                - sort_number: 1
                  cost_name: Transaction Fee
                  currency: USD
                  cost_values:
                    successful:
                      fixed_fee: 0.3
                      percentage: 2.9
                    unsuccessful:
                      fixed_fee: 0
                      percentage: 0
      responses:
        '201':
          description: Creado
          content:
            application/json:
              schema:
                type: object
                properties:
                  connection_id:
                    type: string
                    example: f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e
                  merchant_connection_id:
                    type: string
                    example: stripe-us-prod-001
                  provider_id:
                    type: string
                    example: STRIPE
                  status:
                    type: string
                    example: ACTIVE
                  flow_type:
                    type: string
                    example: PAYIN
                  payment_methods:
                    type: array
                    items:
                      type: string
                    example:
                      - CARD
                  params:
                    type: array
                    items:
                      type: object
                  costs:
                    type: array
                    items:
                      type: object
                  created_at:
                    type: string
                    format: date-time
                    example: '2026-05-12T10:24:00Z'
                  updated_at:
                    type: string
                    format: date-time
                    example: '2026-05-12T10:24:00Z'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: validation_error
                  code:
                    type: string
                    example: MISSING_REQUIRED_PARAM
                  message:
                    type: string
                    example: Required param 'SECRET_KEY' is missing
                  details:
                    type: object
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: auth_error
                  code:
                    type: string
                    example: NOT_AUTHENTICATED
                  message:
                    type: string
                    example: Not authenticated
        '409':
          description: Conflicto
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: conflict
                  code:
                    type: string
                    example: CONNECTION_MERCHANT_ID_CONFLICT
                  message:
                    type: string
                    example: >-
                      A connection with this merchant_connection_id already
                      exists
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>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.