> ## 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.

# Actualizar una conexión

> Actualiza parcialmente una conexión. Solo se aplican los campos que envías; los secretos permanecen enmascarados.

Actualiza parcialmente una conexión que creaste previamente. Solo se aplican los campos presentes en el cuerpo: todo lo que omitas conserva su valor actual.

> [!NOTE]
>
> **Lo que no puedes cambiar aquí:** `provider_id`, `flow_type`, `payment_methods` y el parámetro `INTEGRATION_TYPE` son inmutables. Para cambiar cualquiera de ellos, crea una nueva conexión y redirige tus reglas de enrutamiento hacia ella.

### Parámetros de ruta

**connection\_id** `string` *required*

El id devuelto por [Crear una conexión](https://docs.y.uno/es/reference/organizations/connections/create-connection.md). Debe pertenecer a la cuenta a la que está asociada tu clave de API.

### Cuerpo

**account\_id** `string` *required*

UUID de la cuenta a la que pertenece la conexión.

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

Nueva etiqueta para esta conexión. Máximo 255 caracteres, y debe seguir siendo única dentro de la cuenta. Omítela para conservar la etiqueta actual.

**params** `object[]`

Parámetros a cambiar, como un **arreglo plano** de pares `{param_id, value}`: la misma estructura que en [Crear una conexión](https://docs.y.uno/es/reference/organizations/connections/create-connection.md).

Los parámetros se **combinan por `param_id`** sobre los parámetros actuales de la conexión: un `param_id` que no envías conserva su valor actual. Solo necesitas enviar lo que realmente cambias. Cada `param_id` que envías se valida contra el catálogo del proveedor.

**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.

**costs** `object[]`

Configuración de costos. A diferencia de `params`, `costs` **no se combina**: cuando está presente *reemplaza* toda la tabla de costos de la conexión. Omítela para dejar intactos los costos existentes.

**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. Debe ser una admitida por el proveedor.

**cost\_values** `object`

**successful | unsuccessful**

**fixed\_fee** `number`

Monto de la tarifa fija.

**percentage** `number`

Tarifa porcentual.

### Respuesta

Devuelve la conexión actualizada, con la misma estructura que [Obtener una conexión](https://docs.y.uno/es/reference/organizations/connections/retrieve-connection.md).

**connection\_id** `string`

Identificador único de la conexión. Una actualización no lo modifica.

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

Tu etiqueta interna para esta conexión.

**provider\_id** `string`

El proveedor al que pertenece esta conexión.

**status** `string`

Estado actual.

**flow\_type** `string`

Siempre `PAYIN`.

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

Lista de métodos de pago admitidos.

**params** `object[]`

El conjunto completo de parámetros de la conexión tras la combinación, no solo los que enviaste. 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. Se actualiza con cada actualización exitosa.

```bash cURL — rotate a secret theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl -X PATCH 'https://api.y.uno/v1/connections/f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e' \
  -H 'public-api-key: <YOUR_PUBLIC_KEY>' \
  -H 'private-secret-key: <YOUR_SECRET_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "params": [
      { "param_id": "SECRET_KEY", "value": "sk_live_new..." }
    ]
  }'
```

```bash cURL — rename theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl -X PATCH 'https://api.y.uno/v1/connections/f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e' \
  -H 'public-api-key: <YOUR_PUBLIC_KEY>' \
  -H 'private-secret-key: <YOUR_SECRET_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "merchant_connection_id": "stripe-us-prod-002"
  }'
```

```json 200 OK theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "connection_id": "f1a3c4d5-7b8e-4a2c-9d1e-3f4a5b6c7d8e",
  "merchant_connection_id": "stripe-us-prod-002",
  "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-12T11:02:17Z"
}
```

```json 400 — Unknown Param theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "type": "validation_error",
  "code": "UNKNOWN_PARAM",
  "message": "Param 'FOO' is not part of provider 'STRIPE' catalog",
  "details": { "provider_id": "STRIPE", "param_id": "FOO" }
}
```

```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-002' already exists in this account",
  "details": { "merchant_connection_id": "stripe-us-prod-002" }
}
```

> [!NOTE]
>
> **Manejo de secretos:** los parámetros marcados como `secret: true` en el catálogo siempre se devuelven como `"value": "***"`. Reenviar `"***"` no es la forma de conservar un secreto: simplemente omite el `param_id` por completo y se conserva su valor almacenado.

### Errores

| HTTP | `code` |
| - | - |
| `400` | `UNKNOWN_PARAM` Un `param_id` no forma parte del catálogo del proveedor. |
| `400` | `INVALID_PARAM_VALUE` Un valor no coincide con el `field_type` del catálogo ni con las opciones permitidas. |
| `400` | `UNSUPPORTED_CURRENCY` Un `costs[].currency` no está en la lista de monedas admitidas por el proveedor. |
| `400` | `VALIDATION_ERROR` `connection_id` no es un UUID válido, o `merchant_connection_id` supera los 255 caracteres. |
| `400` | `MALFORMED_BODY` El cuerpo no es un JSON válido. |
| `401` | `NOT_AUTHENTICATED` Clave de API ausente o no válida. |
| `404` | `CONNECTION_NOT_FOUND` `connection_id` desconocido, o el id pertenece a otra cuenta. |
| `409` | `CONNECTION_MERCHANT_ID_CONFLICT` `merchant_connection_id` ya existe en esta cuenta. |


## OpenAPI

````yaml openapi/es/organizations/connections/update-connection.json PATCH /connections/{connection_id}
openapi: 3.1.0
info:
  title: Connections API - Update
  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/{connection_id}:
    patch:
      summary: Actualizar una conexión
      description: >-
        Actualiza parcialmente una conexión. Solo se aplican los campos
        presentes en el cuerpo.
      operationId: update-connection
      parameters:
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
              properties:
                account_id:
                  type: string
                  format: uuid
                  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                merchant_connection_id:
                  type: string
                  maxLength: 255
                  example: stripe-us-prod-002
                params:
                  type: array
                  items:
                    type: object
                    properties:
                      param_id:
                        type: string
                        example: SECRET_KEY
                      value:
                        type: string
                        example: sk_live_...
                costs:
                  type: array
                  items:
                    type: object
                    properties:
                      sort_number:
                        type: integer
                        example: 1
                      cost_name:
                        type: string
                        example: Transaction Fee
                      currency:
                        type: string
                        example: USD
                      cost_values:
                        type: object
                        properties:
                          successful:
                            type: object
                            properties:
                              fixed_fee:
                                type: number
                                example: 0.25
                              percentage:
                                type: number
                                example: 2.7
                          unsuccessful:
                            type: object
                            properties:
                              fixed_fee:
                                type: number
                                example: 0
                              percentage:
                                type: number
                                example: 0
      responses:
        '200':
          description: OK
          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-002
                  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
                      properties:
                        param_id:
                          type: string
                          example: SECRET_KEY
                        value:
                          type: string
                          example: '***'
                  costs:
                    type: array
                    items:
                      type: object
                      properties:
                        sort_number:
                          type: integer
                          example: 1
                        cost_name:
                          type: string
                          example: Transaction Fee
                        currency:
                          type: string
                          example: USD
                  created_at:
                    type: string
                    format: date-time
                    example: '2026-05-12T10:24:00Z'
                  updated_at:
                    type: string
                    format: date-time
                    example: '2026-05-12T11:02:17Z'
        '400':
          description: Solicitud incorrecta
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: validation_error
                  code:
                    type: string
                    example: UNKNOWN_PARAM
                  message:
                    type: string
                    example: Param 'FOO' is not part of provider 'STRIPE' catalog
        '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
        '404':
          description: No encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: not_found
                  code:
                    type: string
                    example: CONNECTION_NOT_FOUND
                  message:
                    type: string
                    example: Connection '...' was not found
        '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 merchant_connection_id
                      'stripe-us-prod-002' already exists in this account
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.