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

# Incrementar autorización

> Aumenta una retención de autorización existente en un monto delta, sin crear una nueva autorización.

Esta solicitud aumenta el monto de un pago previamente autorizado (una autorización incremental). Está diseñada para escenarios de monto abierto (carga de vehículos eléctricos, combustible, hotelería, alquiler de autos), en los que primero autorizas un monto pequeño y haces crecer la retención a medida que se conoce el monto final, y luego capturas una sola vez con la [API de captura](https://docs.y.uno/es/reference/payments/capture-authorization.md).

El `amount` que envías es un **delta**: cuánto se suma al monto autorizado actual. Yuno lo traduce a la semántica que espera cada proveedor.

Cada incremento crea su propia transacción `AUTHORIZE_INCREMENT` con un resultado por incremento, visible en [Retrieve Payment](https://docs.y.uno/es/reference/payments/retrieve-payment-by-id-v2.md). Los incrementos se notifican con el [evento de webhook](https://docs.y.uno/es/docs/webhooks/events.md) `payment.authorize`, así que suscríbete al disparador `AUTHORIZE` para recibirlos; no existe un evento de incremento separado. Un incremento exitoso aumenta `payment.amount.authorized`; `payment.amount.value` conserva el monto original. Un incremento rechazado deja intacto el monto autorizado previamente. Se pueden hacer varios incrementos sobre la misma autorización, pero deben ser secuenciales: un nuevo incremento solicitado mientras otro anterior sigue en curso devuelve un `400`.

Ten en cuenta que esta solicitud requiere un `X-Idempotency-Key`. Consulta la página [Authentication](https://docs.y.uno/es/reference/getting-started/authentication.md#idempotency) para obtener más información.

## Capturar después de los incrementos

Una [captura](https://docs.y.uno/es/reference/payments/capture-authorization.md) con un `amount` explícito puede liquidar cualquier monto hasta el total autorizado actual (la autorización original más todos los incrementos exitosos). Una captura **sin monto** liquida la retención actual completa de la transacción: el monto autorizado original más todos los incrementos `SUCCEEDED` de esa transacción. Los incrementos que sigan en `PENDING` al momento de la captura no se incluyen.

> [!WARNING]
>
> **La autorización original debe estar habilitada para incrementos**
>
> Algunos proveedores solo permiten incrementos en autorizaciones creadas como retenciones de preautorización. Define `authorization_type: "PRE_AUTHORIZATION"` (junto con `capture: false`) al [crear el pago](https://docs.y.uno/es/reference/payments/create-payment.md); consulta la guía [Cancel and Capture Flow](https://docs.y.uno/es/docs/payment-features/Cancel-and-capture-flow.md#pre-authorization-holds-authorization_type). Cuando el proveedor rechaza el incremento, porque la autorización original no era una preautorización o porque se superaron los límites de incremento del proveedor (por ejemplo, más de 10 incrementos o un total superior a 5 veces el monto inicial), la transacción de incremento se devuelve con el código de respuesta `AUTHORIZATION_NOT_INCREMENTABLE`.

## Compatibilidad por proveedor

La compatibilidad depende del proveedor. Si el proveedor enrutado para el pago no admite autorizaciones incrementales, la llamada igualmente devuelve `201`, pero con una transacción de incremento cuyo `status` es `ERROR` y cuyo `response_code` es `OPERATION_NOT_SUPPORTED_BY_PROVIDER`. No es un error HTTP, por lo que debes basarte en el `status` de la transacción y no en el código de estado HTTP. El monto autorizado previamente queda intacto.

**Revolut** es actualmente el único proveedor con compatibilidad con autorización incremental.

| Proveedor | Resultado | Notas |
| - | - | - |
| Revolut | Asíncrono | La transacción se devuelve como `PENDING`; el resultado final se entrega mediante el webhook `payment.authorize`. Los incrementos requieren que la autorización original se haya creado con `authorization_type: "PRE_AUTHORIZATION"`, están disponibles solo con tarjeta, Apple Pay y Google Pay, solo se pueden probar en producción (no están disponibles en sandbox) y se limitan a 10 incrementos secuenciales con un total de hasta 5 veces el monto inicial |

Otros proveedores (Stripe, Adyen, Checkout.com, CyberSource) están en la hoja de ruta y aún no están disponibles; llamar al endpoint con ellos hoy devuelve la transacción `OPERATION_NOT_SUPPORTED_BY_PROVIDER` descrita arriba.


## OpenAPI

````yaml openapi/es/payments/increment-authorization.json POST /payments/{payment_id}/transactions/{transaction_id}/increment
openapi: 3.1.0
info:
  title: payment-api-increment-authorization
  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: []
    sec2: []
paths:
  /payments/{payment_id}/transactions/{transaction_id}/increment:
    post:
      summary: Incrementar autorización
      description: >-
        Aumenta una retención de autorización existente en un monto delta. Cada
        incremento crea su propia transacción `AUTHORIZE_INCREMENT` con un
        resultado por incremento.
      operationId: increment-authorization
      parameters:
        - name: payment_id
          in: path
          description: El identificador único del pago (UUID, 36 caracteres).
          schema:
            type: string
          required: true
        - name: transaction_id
          in: path
          description: >-
            El identificador único de la transacción AUTHORIZE original que se
            va a incrementar (UUID, 36 caracteres).
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - merchant_reference
              properties:
                amount:
                  type: object
                  description: >-
                    El monto que se SUMA al monto autorizado actual (un delta,
                    no el nuevo total). La moneda debe coincidir con la de la
                    autorización original.
                  required:
                    - value
                    - currency
                  properties:
                    value:
                      type: number
                      description: El delta que se suma al monto autorizado actual.
                      example: 50
                    currency:
                      type: string
                      description: >-
                        Código de moneda ISO 4217 de tres letras. Debe coincidir
                        con el de la autorización original.
                      example: EUR
                merchant_reference:
                  type: string
                  description: La referencia de este incremento.
                description:
                  type: string
                  description: Descripción opcional del incremento.
            examples:
              Increment by 50:
                value:
                  amount:
                    value: 50
                    currency: EUR
                  merchant_reference: session-8842-inc-2
                  description: EV charging session top-up
      responses:
        '201':
          description: '201'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      Identificador único de la transacción de incremento
                      (UUID).
                  type:
                    type: string
                    description: Tipo de transacción.
                    example: AUTHORIZE_INCREMENT
                  status:
                    type: string
                    enum:
                      - SUCCEEDED
                      - DECLINED
                      - PENDING
                      - ERROR
                    description: >-
                      Resultado por incremento. `SUCCEEDED`: la retención se
                      aumentó. `DECLINED`: el emisor o el proveedor rechazó este
                      incremento; el monto autorizado anterior se mantiene.
                      `PENDING`: el proveedor procesa los incrementos de forma
                      asíncrona; el resultado final se entrega por webhook.
                      `ERROR`: no se pudo procesar el incremento.
                  amount:
                    type: object
                    description: El delta sumado por este incremento.
                    properties:
                      value:
                        type: number
                        example: 50
                      currency:
                        type: string
                        example: EUR
                  merchant_reference:
                    type: string
                    description: La referencia enviada en la solicitud.
                  parent_transaction_id:
                    type: string
                    description: >-
                      El `transaction_id` de la transacción AUTHORIZE original a
                      la que pertenece este incremento.
                  response_code:
                    type: string
                    description: >-
                      Código de respuesta de Yuno para este incremento: el
                      subestado de la transacción cuando el proveedor devuelve
                      uno; de lo contrario, el estado de la transacción (por
                      ejemplo `SUCCEEDED`, `PENDING_PROVIDER_CONFIRMATION`,
                      `AUTHORIZATION_NOT_INCREMENTABLE`). No es un código de
                      emisor ISO 8583. `AUTHORIZATION_NOT_INCREMENTABLE` indica
                      que el proveedor rechazó el incremento, ya sea porque la
                      autorización original no se creó como `PRE_AUTHORIZATION`
                      o porque se superaron los límites de incremento del
                      proveedor (por ejemplo, más de 10 incrementos o un total
                      superior a 5 veces el monto inicial en Revolut).
                  response_message:
                    type: string
                    description: Detalle legible del resultado.
                  provider_data:
                    type: object
                    description: >-
                      Identificadores y estado sin procesar del proveedor para
                      este incremento.
                  payment:
                    type: object
                    description: El pago principal después de este incremento.
                    properties:
                      id:
                        type: string
                        description: Identificador único del pago (UUID).
                      status:
                        type: string
                        example: AUTHORIZED
                      amount:
                        type: object
                        description: >-
                          Montos del pago principal. Los incrementos no cambian
                          `value`; aumentan `authorized`.
                        properties:
                          value:
                            type: number
                            description: >-
                              El monto original del pago. Los incrementos no lo
                              modifican.
                            example: 100
                          authorized:
                            type: number
                            description: >-
                              Monto autorizado total: la autorización original
                              más todos los incrementos `SUCCEEDED`. Cuando el
                              proveedor procesa los incrementos de forma
                              asíncrona (Revolut), el incremento sigue en
                              `PENDING` en esta respuesta, por lo que
                              `authorized` aún no lo incluye; el total aumentado
                              se refleja una vez que el incremento tiene éxito.
                            example: 150
                          currency:
                            type: string
                            example: EUR
              examples:
                Approved Increment:
                  value:
                    id: 8f2f4bce-1d2f-4f6e-9a3b-0c1e5d3a7b21
                    type: AUTHORIZE_INCREMENT
                    status: SUCCEEDED
                    amount:
                      value: 50
                      currency: EUR
                    merchant_reference: session-8842-inc-2
                    parent_transaction_id: 1a71c7b7-80c2-4ba5-b601-4d34d48c0e18
                    response_code: SUCCEEDED
                    response_message: Approved
                    provider_data:
                      id: prov-ref-001
                      status: ...
                    payment:
                      id: d19205be-1a70-4c13-a4e6-8b7a9f3e2c11
                      status: PENDING
                      sub_status: AUTHORIZED
                      amount:
                        value: 100
                        authorized: 150
                        currency: EUR
                Pending Increment (async provider):
                  value:
                    id: 8f2f4bce-1d2f-4f6e-9a3b-0c1e5d3a7b21
                    type: AUTHORIZE_INCREMENT
                    status: PENDING
                    amount:
                      value: 50
                      currency: EUR
                    merchant_reference: session-8842-inc-2
                    parent_transaction_id: 1a71c7b7-80c2-4ba5-b601-4d34d48c0e18
                    response_code: PENDING_PROVIDER_CONFIRMATION
                    response_message: Increment in progress; final result delivered via webhook
                    provider_data:
                      id: prov-ref-001
                      status: ...
                    payment:
                      id: d19205be-1a70-4c13-a4e6-8b7a9f3e2c11
                      status: PENDING
                      sub_status: AUTHORIZED
                      amount:
                        value: 100
                        authorized: 100
                        currency: EUR
                Declined Increment:
                  value:
                    id: 8f2f4bce-1d2f-4f6e-9a3b-0c1e5d3a7b21
                    type: AUTHORIZE_INCREMENT
                    status: DECLINED
                    amount:
                      value: 50
                      currency: EUR
                    merchant_reference: session-8842-inc-2
                    parent_transaction_id: 1a71c7b7-80c2-4ba5-b601-4d34d48c0e18
                    response_code: DECLINED
                    response_message: Insufficient funds
                    provider_data:
                      id: prov-ref-001
                      status: ...
                    payment:
                      id: d19205be-1a70-4c13-a4e6-8b7a9f3e2c11
                      status: PENDING
                      sub_status: AUTHORIZED
                      amount:
                        value: 100
                        authorized: 100
                        currency: EUR
                Not Incrementable:
                  value:
                    id: 8f2f4bce-1d2f-4f6e-9a3b-0c1e5d3a7b21
                    type: AUTHORIZE_INCREMENT
                    status: DECLINED
                    amount:
                      value: 50
                      currency: EUR
                    merchant_reference: session-8842-inc-2
                    parent_transaction_id: 1a71c7b7-80c2-4ba5-b601-4d34d48c0e18
                    response_code: AUTHORIZATION_NOT_INCREMENTABLE
                    response_message: >-
                      The provider rejected the increment (not a
                      pre-authorization, or the provider's increment limits were
                      exceeded)
                    provider_data:
                      id: prov-ref-001
                      status: ...
                    payment:
                      id: d19205be-1a70-4c13-a4e6-8b7a9f3e2c11
                      status: PENDING
                      sub_status: AUTHORIZED
                      amount:
                        value: 100
                        authorized: 100
                        currency: EUR
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Invalid request:
                  value:
                    code: INVALID_REQUEST
                    messages:
                      - Invalid request
                Payment or transaction not found:
                  value:
                    code: TRANSACTION_NOT_FOUND
                    messages:
                      - Payment or transaction not found
                Transaction not an active authorization:
                  value:
                    code: INVALID_STATUS_WITH_FORMAT
                    messages:
                      - >-
                        The payment is not in an authorized hold state, the
                        authorization is not SUCCEEDED (already captured,
                        voided, or expired), or another increment is already in
                        progress
                Currency mismatch:
                  value:
                    code: INVALID_CURRENCY
                    messages:
                      - Currency does not match the original authorization
                Target transaction is not an authorization:
                  value:
                    code: INVALID_TRANSACTION_TYPE
                    messages:
                      - >-
                        The target transaction is not an AUTHORIZE transaction.
                        Use the transaction_id of the original authorization,
                        not a capture or purchase transaction.
                Invalid amount:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        Invalid amount. The increment amount (delta) must be
                        greater than zero.
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_REQUEST
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid request
        '401':
          description: '401'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: UNAUTHORIZED
                    messages:
                      - Invalid credentials
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_REQUEST
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid request
        '403':
          description: '403'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: FORBIDDEN
                    messages:
                      - Forbidden
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_REQUEST
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid request
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      x-default: <Your public-api-key>
      name: public-api-key
    sec1:
      type: apiKey
      in: header
      x-default: <Your private-secret-key>
      name: private-secret-key
    sec2:
      type: apiKey
      in: header
      x-default: <Your X-Idempotency-Key>
      name: X-Idempotency-Key

````

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