> ## 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 un plan de cuotas

> Crea un plan de cuotas que define el rango de montos, el BIN de la tarjeta, la moneda y las reglas de disponibilidad

Yuno te permite crear planes de cuotas para ofrecer a tus clientes. Estos planes pueden usarse según factores como el monto a pagar, la moneda y la tarjeta utilizada, como se describe a continuación:

* **Filtrado por rango de montos (obligatorio):** El sistema comprueba si el plan de cuotas es adecuado para el monto específico de tu transacción. Solo se consideran los planes que pueden manejar ese monto.
* **BIN de la tarjeta:** El sistema verifica si el BIN de tu tarjeta coincide con los permitidos para ciertos planes de cuotas. Si hay coincidencia, ese plan se considera.
* **Moneda específica:** Solo se consideran los planes que funcionan con la moneda que estás usando.
* **Disponibilidad del plan:** El sistema comprueba si el plan de cuotas está activo. Solo se consideran los planes que no han expirado y están disponibles.

> [!NOTE]
>
> **Definir el ID del plan**
>
> El `plan_id` solo es necesario cuando se aplica un plan de cuotas fijo que no cambia durante la compra. Si no se envía `installment.plan_id`, el SDK buscará automáticamente entre todos los planes de cuotas disponibles asociados a esa cuenta y seleccionará el que considere más adecuado. Debes incluir el `plan_id` para asegurar que se aplique un plan específico.

> [!NOTE]
>
> **Cuotas del comercio**
>
> Este endpoint solo es necesario para la [integración de cuotas del comercio](https://docs.y.uno/es/docs/payment-features/installments.md). Para las cuotas definidas por el proveedor, usamos el plan de cuotas definido por tu proveedor de pagos.

Para las cuotas creadas por el comercio, también puedes especificar el plan para cada sesión de checkout usando el `plan_id` al [crear la sesión](https://docs.y.uno/es/reference/checkout-sessions/create-checkout-session.md). Si no lo envías, usaremos el plan de cuotas que coincida con las condiciones establecidas para la sesión de checkout.


## OpenAPI

````yaml openapi/es/installments/create-installments-plan.json POST /installments-plans
openapi: 3.1.0
info:
  title: installments
  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:
  /installments-plans:
    post:
      summary: Crear plan de cuotas
      operationId: create-installments-plan
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - account_id
                - merchant_reference
                - installments_plan
              properties:
                name:
                  type: string
                  description: El nombre del plan de cuotas (MAX 255; MIN 3)
                account_id:
                  type: array
                  description: >-
                    El identificador único de la cuenta o cuentas que tendrán el
                    plan de cuotas (UUID; 36 caracteres).
                  default: '{{account_id}}'
                  items:
                    type: string
                merchant_reference:
                  type: string
                  description: Identificación del plan de cuotas (MAX 255; MIN 3)
                installments_plan:
                  type: array
                  description: Definición de las cuotas disponibles para cada escenario
                  items:
                    properties:
                      installment:
                        type: integer
                        description: >-
                          La cantidad de cuotas mensuales que pueden elegir los
                          compradores
                        format: int32
                      rate:
                        type: number
                        description: >-
                          La tasa que aplica el proveedor de pagos al monto
                          final de la transacción cuando se usan cuotas. El
                          valor se ingresa como multiplicador, no como
                          porcentaje. Por ejemplo, para aplicar una tasa del 20
                          %, ingresa `1.20` en lugar de `20`.
                        format: float
                      financial_costs:
                        type: array
                        description: >-
                          Detalles opcionales de los costos financieros de esta
                          opción de cuotas.
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              description: >-
                                El identificador del tipo de costo financiero
                                (MIN 3; MAX 255).


                                <br/> Ejemplo: `CFT`, `TEA`, `CET`, `CAT`
                            rate:
                              type: number
                              description: >-
                                La tasa del costo financiero como número decimal
                                (por ejemplo, 45.25 para 45.25%).
                              minimum: 0
                              maximum: 100000
                              format: float
                          required:
                            - type
                            - rate
                      type:
                        type: string
                        description: >-
                          Tipo de cuota. Solo disponible para Ecuador y México.
                          Merchant se refiere a pagos diferidos con intereses e
                          Issuer, a pagos diferidos sin intereses
                        enum:
                          - MERCHANT_INSTALLMENTS
                          - ISSUER_INSTALLMENTS
                    required:
                      - installment
                    type: object
                country_code:
                  type: string
                  description: El país del emisor (ISO 3166-1 MAX 2; MIN 2)
                brand:
                  type: array
                  description: Información de la marca de la tarjeta (MAX 255; MIN 3).
                  items:
                    type: string
                issuer:
                  type: string
                  description: Emisor de la tarjeta (MAX 255; MIN 3)
                iin:
                  type: array
                  description: >-
                    El número de identificación del emisor (IIN) corresponde a
                    los primeros dígitos del número de una tarjeta de pago
                    emitida por una institución financiera (MAX 8; MIN 6)
                  items:
                    type: string
                first_installment_deferral:
                  type: integer
                  description: >-
                    La cantidad de meses que se esperan para debitar la primera
                    cuota (MAX: 3).
                  format: int32
                amount:
                  type: object
                  description: >-
                    Los montos para los que estará disponible el plan de cuotas.
                    Si es null, está disponible para cualquier monto.
                  required:
                    - currency
                  properties:
                    currency:
                      type: string
                      description: >-
                        La moneda con la que se hace el pago (ISO 4217 MAX 3;
                        MIN 3)
                    min_value:
                      type: number
                      description: >-
                        El monto mínimo para el que se podrá usar el plan de
                        cuotas (múltiplo de 0.0001).
                      format: float
                    max_value:
                      type: number
                      description: >-
                        El monto máximo para el que se podrá usar el plan de
                        cuotas (múltiplo de 0.0001).
                      format: float
                availability:
                  type: object
                  description: >-
                    Las fechas en las que estará disponible el plan de cuotas.
                    Si es null, no tiene fecha de finalización
                  properties:
                    start_at:
                      type: string
                      description: >-
                        La fecha de inicio desde la cual se podrá usar el plan
                        de cuotas (formato UTC)
                      format: date-time
                    finish_at:
                      type: string
                      description: >-
                        La fecha de fin hasta la cual se podrá usar el plan de
                        cuotas (formato UTC)
                      format: date-time
                payment_method_type:
                  type: string
                  description: >-
                    Permite especificar el tipo de método de pago al crear un
                    plan de cuotas. `CARD` coincide por el IIN de la tarjeta,
                    mientras que `NU_PAY_ENROLLMENT` y `APPLE_PAY` coinciden sin
                    él. Los planes solo se ofrecen al método de pago para el que
                    se crearon.
                  enum:
                    - CARD
                    - NU_PAY_ENROLLMENT
                    - APPLE_PAY
            examples:
              Request Example:
                value:
                  name: plan_007
                  account_id:
                    - '{{account-code}}'
                  merchant_reference: Test
                  installments_plan:
                    - installment: 1
                      rate: 1
                    - installment: 3
                      rate: 1
                      financial_costs:
                        - type: CFT
                          rate: 45.25
                        - type: TEA
                          rate: 38.5
                    - installment: 6
                      rate: 1
                    - installment: 9
                      rate: 1
                    - installment: 12
                      rate: 1
                  country_code: CO
                  amount:
                    currency: COP
                    min_value: 0
                    max_value: 100000000
                  availability:
                    start_at: '2023-09-12T00:00:00Z'
                    finish_at: '2030-09-20T00:00:00Z'
                  payment_method_type: NU_PAY_ENROLLMENT
      responses:
        '200':
          description: >-
            Hoy la respuesta devuelve `amount.Currency` con C mayúscula, no
            `amount.currency`. Lee la clave sin distinguir mayúsculas de
            minúsculas.
          content:
            application/json:
              examples:
                Result:
                  value:
                    id: 4d573425-33f9-4c46-b009-2c7e749b0ec7
                    name: plan_007
                    account_id:
                      - f7c5fe77-721b-49c2-84d3-957748df3c2c
                    merchant_reference: Test
                    installments_plan:
                      - installment: 1
                        rate: 1
                        provider_id: ''
                      - installment: 3
                        rate: 1
                        provider_id: ''
                        financial_costs:
                          - type: CFT
                            rate: 45.25
                            formatted_value: 45,25%
                          - type: TEA
                            rate: 38.5
                            formatted_value: 38,50%
                      - installment: 6
                        rate: 1
                        provider_id: ''
                      - installment: 9
                        rate: 1
                        provider_id: ''
                      - installment: 12
                        rate: 1
                        provider_id: ''
                    source: ''
                    provider_id: ''
                    scheme: ''
                    brand:
                      - VISA
                    issuer: ''
                    issuer_id: ''
                    iin: null
                    country_code: US
                    first_installment_deferral: 0
                    amount:
                      currency: USD
                      min_value: 0
                      max_value: 100000000
                    availability:
                      start_at: '2023-09-12T00:00:00Z'
                      finish_at: '2030-09-20T00:00:00Z'
                    payment_method_type: NU_PAY_ENROLLMENT
                    created_at: '2023-10-11T17:52:31.886178246Z'
                    updated_at: '2023-10-11T17:52:31.886178246Z'
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 4d573425-33f9-4c46-b009-2c7e749b0ec7
                  name:
                    type: string
                    example: plan_007
                  account_id:
                    type: array
                    items:
                      type: string
                      example: f7c5fe77-721b-49c2-84d3-957748df3c2c
                  merchant_reference:
                    type: string
                    example: Test
                  installments_plan:
                    type: array
                    items:
                      type: object
                      properties:
                        installment:
                          type: integer
                          example: 1
                          default: 0
                        rate:
                          type: number
                          example: 1
                          default: 0
                        provider_id:
                          type: string
                          example: ''
                        financial_costs:
                          type: array
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - CFT
                                  - TEA
                                  - CET
                                  - CAT
                              rate:
                                type: number
                                format: float
                              formatted_value:
                                type: string
                  type:
                    type: string
                    example: ''
                  source:
                    type: string
                    example: ''
                  provider_id:
                    type: string
                    example: ''
                  scheme:
                    type: string
                    example: ''
                  brand:
                    type: array
                    items:
                      type: string
                      example: VISA
                  issuer:
                    type: string
                    example: ''
                  issuer_id:
                    type: string
                    example: ''
                  iin: {}
                  country_code:
                    type: string
                    example: US
                  first_installment_deferral:
                    type: integer
                    example: 0
                    default: 0
                  amount:
                    type: object
                    properties:
                      currency:
                        type: string
                        example: USD
                      min_value:
                        type: integer
                        example: 0
                        default: 0
                      max_value:
                        type: integer
                        example: 100000000
                        default: 0
                  availability:
                    type: object
                    properties:
                      start_at:
                        type: string
                        example: '2023-09-12T00:00:00Z'
                      finish_at:
                        type: string
                        example: '2030-09-20T00:00:00Z'
                  created_at:
                    type: string
                    example: '2023-10-11T17:52:31.886178246Z'
                  updated_at:
                    type: string
                    example: '2023-10-11T17:52:31.886178246Z'
                  payment_method_type:
                    type: string
                    enum:
                      - CARD
                      - NU_PAY_ENROLLMENT
                      - APPLE_PAY
                    example: NU_PAY_ENROLLMENT
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - Invalid request
              schema:
                type: object
                properties: {}
      deprecated: false
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.