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

# Cambiar el método de pago de una suscripción externa

> Cambia una suscripción de Stripe Billing a otro método de pago que el cliente ya registró en Yuno, sin realizar un pago.

Usa este endpoint con las [suscripciones de Stripe Billing](https://docs.y.uno/es/docs/payment-features/subscriptions/stripe-billing.md) para cambiar una suscripción a otro método de pago almacenado del mismo cliente.

> [!NOTE]
>
> **No se realiza ningún pago**
>
> Yuno no cobra al cliente y no ejecuta una verificación de \$0 ni 3DS. Yuno establece el nuevo método de pago como el predeterminado de la suscripción en Stripe, y las próximas renovaciones se cobran con él.

## Solicitud

| Campo | Descripción |
| - | - |
| `external_subscription_id` (ruta) | El ID de la suscripción de Stripe (`sub_...`), de entre 3 y 255 caracteres. |
| `account_id` | La cuenta de Yuno incorporada al puente de facturación (UUID). |
| `customer_payer.id` | El **ID de cliente de Yuno** (UUID) propietario de la suscripción. No es el ID de cliente de Stripe (`cus_...`). |
| `vaulted_token` | El token almacenado (UUID) de uno de los métodos de pago registrados de ese cliente. |

El encabezado `X-Idempotency-Key` es obligatorio. Repetir la misma clave con la misma solicitud devuelve el primer resultado. Enviar el método de pago que la suscripción ya cobra devuelve `200` y no cambia nada.

Esta API se habilita por cuenta. Contacta a tu Key Account Manager para solicitar acceso.

## Errores

| Estado | Código | Significado | Qué hacer |
| - | - | - | - |
| `400` | `INVALID_PARAMETERS` | Falta un campo o el encabezado `X-Idempotency-Key`, o tiene un formato incorrecto, o la clave ya se usó para otra suscripción o método de pago. | Corrige la solicitud. Usa una clave nueva para un cambio diferente. |
| `400` | `CUSTOMER_NOT_FOUND` | El cliente no existe en la cuenta. | Verifica que `customer_payer.id` sea el ID de cliente de Yuno, no el ID `cus_` de Stripe. |
| `400` | `VAULTED_TOKEN_NOT_FOUND` | El `vaulted_token` no es uno de los métodos de pago del cliente. | Usa un token de los [métodos de pago registrados](https://docs.y.uno/es/reference/payment-methods-direct-workflow/retrieve-enrolled-payment-methods-api.md) del cliente. |
| `400` | `EXTERNAL_SUBSCRIPTION_NOT_FOUND` | No hay una suscripción externa activa con este ID para la cuenta. | Verifica el ID de la suscripción de Stripe y la cuenta. |
| `400` | `CUSTOMER_MISMATCH` | La suscripción pertenece a otro cliente. | Envía el cliente propietario de la suscripción. |
| `403` | `PRODUCT_NOT_ENABLED` | La cuenta no está habilitada para el puente de facturación. | Contacta a tu Key Account Manager. |
| `409` | `CONCURRENT_CHANGE` | Otro cambio de método de pago de esta suscripción se completó primero. | Revisa la suscripción en Stripe antes de enviar otro cambio. |
| `502` | `BILLING_PLATFORM_ERROR` | La plataforma de facturación no pudo confirmar el cambio. Se mantiene el método de pago anterior. | Reintenta con un nuevo `X-Idempotency-Key`. |


## OpenAPI

````yaml openapi/es/subscriptions/change-external-subscription-payment-method.json POST /external-subscriptions/{external_subscription_id}/payment-method
openapi: 3.1.0
info:
  title: subscription
  version: 1.0.2
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /external-subscriptions/{external_subscription_id}/payment-method:
    post:
      summary: Change External Subscription Payment Method
      description: >-
        Mueve una suscripción externa (una suscripción de Stripe Billing
        vinculada a través del billing bridge) a otro método de pago que el
        cliente ya inscribió en Yuno, sin un pago.


        No se realiza ningún pago: Yuno no cobra al cliente y no ejecuta una
        verificación de $0 ni 3DS. Las próximas renovaciones cobran el nuevo
        método de pago.


        `customer_payer.id` es el ID de cliente de Yuno, no el ID de cliente de
        Stripe (`cus_...`). Enviar el método de pago que la suscripción ya cobra
        devuelve `200` y no cambia nada.


        Esta API se habilita por cuenta: contacta a tu Key Account Manager para
        solicitar acceso.
      operationId: change-external-subscription-payment-method
      parameters:
        - name: external_subscription_id
          in: path
          description: >-
            El ID de la suscripción en la plataforma de facturación, por ejemplo
            el ID de suscripción de Stripe (`sub_...`). Entre 3 y 255
            caracteres.
          schema:
            type: string
            minLength: 3
            maxLength: 255
          required: true
          example: sub_1QF2abc
        - name: X-Idempotency-Key
          in: header
          description: >-
            Clave única para este cambio, por ejemplo un UUID. Obligatoria: una
            solicitud sin ella devuelve `400` `INVALID_PARAMETERS`. Repetir la
            misma clave con la misma solicitud devuelve el resultado de la
            primera solicitud. Reutilizar una clave para otra suscripción u otro
            método de pago devuelve `400` `INVALID_PARAMETERS`. Para reintentar
            después de un `502`, envía una clave nueva.
          schema:
            type: string
          required: true
          example: 7c2e0a4b-3f5d-4c1e-9b8a-6d2f1e0c9a77
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
                - customer_payer
                - vaulted_token
              properties:
                account_id:
                  type: string
                  format: uuid
                  description: >-
                    El identificador único (UUID) de la cuenta de Yuno
                    incorporada al billing bridge.
                  examples:
                    - 9104911d-5df9-429e-8488-ad41abea1a4b
                customer_payer:
                  type: object
                  required:
                    - id
                  description: >-
                    El cliente que es dueño de la suscripción y del método de
                    pago.
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: >-
                        El ID de cliente de Yuno (UUID) que es dueño de la
                        suscripción. No es el ID de cliente de Stripe
                        (`cus_...`).
                      examples:
                        - cfae0941-7234-427a-a739-ef4fce966c79
                vaulted_token:
                  type: string
                  format: uuid
                  description: >-
                    El token del vault (UUID) de uno de los métodos de pago
                    inscritos del cliente. La suscripción lo cobra a partir de
                    ahora.
                  examples:
                    - 2deff5c9-da62-4888-8f05-df76ab2967a5
            examples:
              Change the payment method:
                value:
                  account_id: 9104911d-5df9-429e-8488-ad41abea1a4b
                  customer_payer:
                    id: cfae0941-7234-427a-a739-ef4fce966c79
                  vaulted_token: 2deff5c9-da62-4888-8f05-df76ab2967a5
      responses:
        '200':
          description: >-
            La suscripción ahora usa el método de pago de `vaulted_token`.
            También se devuelve, sin cambios, cuando ese método de pago es el
            que la suscripción ya usa.
          content:
            application/json:
              schema:
                type: object
                properties:
                  external_subscription_id:
                    type: string
                    description: >-
                      El ID de la suscripción en la plataforma de facturación
                      externa.
                  account_id:
                    type: string
                    format: uuid
                    description: El ID de cuenta de Yuno de la solicitud.
                  customer_payer:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: El ID de cliente de Yuno de la solicitud.
                  vaulted_token:
                    type: string
                    format: uuid
                    description: >-
                      El token del vault que la suscripción cobra a partir de
                      ahora.
              examples:
                Payment method changed:
                  value:
                    external_subscription_id: sub_1QF2abc
                    account_id: 9104911d-5df9-429e-8488-ad41abea1a4b
                    customer_payer:
                      id: cfae0941-7234-427a-a739-ef4fce966c79
                    vaulted_token: 2deff5c9-da62-4888-8f05-df76ab2967a5
        '400':
          description: >-
            La solicitud no es válida, o no se encontró el cliente, el método de
            pago o la suscripción, o no coinciden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                INVALID_PARAMETERS:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The field 'customer_payer.id' is required and must be a
                        UUID.
                CUSTOMER_NOT_FOUND:
                  value:
                    code: CUSTOMER_NOT_FOUND
                    messages:
                      - The customer does not exist in the account.
                VAULTED_TOKEN_NOT_FOUND:
                  value:
                    code: VAULTED_TOKEN_NOT_FOUND
                    messages:
                      - >-
                        The vaulted_token is not one of the customer's payment
                        methods.
                EXTERNAL_SUBSCRIPTION_NOT_FOUND:
                  value:
                    code: EXTERNAL_SUBSCRIPTION_NOT_FOUND
                    messages:
                      - >-
                        No active external subscription with this id for the
                        account.
                CUSTOMER_MISMATCH:
                  value:
                    code: CUSTOMER_MISMATCH
                    messages:
                      - The external subscription belongs to another customer.
        '403':
          description: >-
            PRODUCT_NOT_ENABLED: la cuenta no está habilitada para el billing
            bridge. Contacta a tu Key Account Manager.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                PRODUCT_NOT_ENABLED:
                  value:
                    code: PRODUCT_NOT_ENABLED
                    messages:
                      - >-
                        External subscriptions are not enabled for this account.
                        Please contact your Key Account Manager.
        '409':
          description: >-
            CONCURRENT_CHANGE: otro cambio de método de pago para esta
            suscripción se completó primero.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                CONCURRENT_CHANGE:
                  value:
                    code: CONCURRENT_CHANGE
                    messages:
                      - >-
                        Another payment method change for this subscription
                        completed first.
        '502':
          description: >-
            BILLING_PLATFORM_ERROR: la plataforma de facturación no pudo
            confirmar el cambio. Se mantiene el método de pago anterior.
            Reintenta con una nueva clave de idempotencia.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                BILLING_PLATFORM_ERROR:
                  value:
                    code: BILLING_PLATFORM_ERROR
                    messages:
                      - >-
                        The billing platform could not confirm the change. The
                        previous payment method stays. Retry with a new
                        idempotency key.
      deprecated: false
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: El código de error.
        messages:
          type: array
          items:
            type: string
          description: Detalles legibles sobre el error.
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
    sec1:
      type: apiKey
      in: header
      name: private-secret-key

````

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