Saltar al contenido principal
POST
Incrementar 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. 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. Los incrementos se notifican con el evento de webhook 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 para obtener más información.

Capturar después de los incrementos

Una captura 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.
La autorización original debe estar habilitada para incrementosAlgunos 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; consulta la guía Cancel and Capture Flow. 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. 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.

Autorizaciones

public-api-key
string
header
predeterminado:<Your public-api-key>
requerido
private-secret-key
string
header
predeterminado:<Your private-secret-key>
requerido
X-Idempotency-Key
string
header
predeterminado:<Your X-Idempotency-Key>
requerido

Parámetros de ruta

payment_id
string
requerido

El identificador único del pago (UUID, 36 caracteres).

transaction_id
string
requerido

El identificador único de la transacción AUTHORIZE original que se va a incrementar (UUID, 36 caracteres).

Cuerpo

application/json
amount
object
requerido

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.

merchant_reference
string
requerido

La referencia de este incremento.

description
string

Descripción opcional del incremento.

Respuesta

201

id
string

Identificador único de la transacción de incremento (UUID).

type
string

Tipo de transacción.

Ejemplo:

"AUTHORIZE_INCREMENT"

status
enum<string>

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.

Opciones disponibles:
SUCCEEDED,
DECLINED,
PENDING,
ERROR
amount
object

El delta sumado por este incremento.

merchant_reference
string

La referencia enviada en la solicitud.

parent_transaction_id
string

El transaction_id de la transacción AUTHORIZE original a la que pertenece este incremento.

response_code
string

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
string

Detalle legible del resultado.

provider_data
object

Identificadores y estado sin procesar del proveedor para este incremento.

payment
object

El pago principal después de este incremento.