Preautorización: crea y captura

Esta guía muestra cómo crear una preautorización (reservar fondos en la tarjeta) y luego capturar ese importe en un segundo paso. El comportamiento es el mismo en conexiones USB y de red. También cubre cómo recuperar las preautorizaciones pendientes. Las operaciones Modify y Remove usan la misma estructura de solicitud que Confirm y solo cambian el valor de Operation.

¿Qué es la preautorización?

La preautorización reserva fondos en la tarjeta del cliente sin capturarlos. Envías una solicitud Create; el TPV devuelve un código de autorización y los datos de la reserva. Luego confirmas la preautorización con esos datos para capturar el importe. Este flujo de dos pasos sirve cuando no conoces el importe final ni el momento de la captura al autorizar.

Antes de comenzar

Antes de empezar:

• Se debe crear y validar un Connector con Polling
• El Modo TPV Integrado debe estar activo
• El terminal y la marca de tarjeta deben admitir la preautorización

Paso 1: Crea la preautorización

Crea la preautorización llamando a la operación Pre-authorization con Operation = Create. Envía el importe y, de forma opcional, las cuotas o el plan. El TPV ejecuta el flujo de la tarjeta y devuelve los datos que necesitas para el Paso 2.

Este ejemplo crea una preautorización de 500,00:

var createRequest = new PreAuthRequest
{
    Operation = PreAuthOperation.Create,
    Amount = 50000
};

var createResult = connector.PreAuthAsync(createRequest);

El TPV ejecuta el flujo de la tarjeta (insertar, acercar, etc.). Cuando la solicitud tiene éxito, la respuesta contiene los datos necesarios para capturar después.

Cuando la preautorización se crea con éxito, el TPV devuelve una respuesta estructurada con todos los detalles de la transacción. Este es un ejemplo de un objeto de respuesta completo:

{
  "Code": 0,
  "Message": "APPROVED",
  "AuthorizationCode": "551437",
  "Amount": 50000,
  "OriginalAmount": 50000,
  "Last4Digits": "1234",
  "CardBrand": "Mastercard",
  "CardType": "Credit",
  "AccountingDate": "2025-08-25T16:11:23.0000000Z",
  "RealDate": "2025-08-25T13:11:50.8570000-03:00",
  "ReservationId": "RES-001",
  "CommerceCode": "1234567890",
  "TerminalId": "GET00123",
  "CardBin": "84168075",
  "CallerId": "123456-789000"
}

Esta respuesta ofrece un conjunto completo de campos que describen el estado y el origen de la reserva. La siguiente tabla detalla los campos más relevantes devueltos en esta fase:

Para capturar los fondos con éxito en el siguiente paso, debes guardar valores específicos de esta respuesta. Estos campos son necesarios para identificar la transacción durante la fase de confirmación:

• AuthorizationCode: identifica la reserva aprobada.
• AccountingDate: se usa como el parámetro OriginalTransactionDate.
• ReservationId: se usa como ReservationCode (opcional, pero recomendado si está disponible).

Después de guardar estos valores, puedes continuar con el paso de confirmación.

Paso 2: Captura la preautorización (confirm)

Para capturar el importe reservado, llama de nuevo a la operación Pre-authorization con Operation = Confirm. Pasa el AuthorizationCode y el OriginalTransactionDate (y de forma opcional el ReservationCode) de la respuesta de Create.

Este es un ejemplo de cómo capturar la preautorización:

// Using data from the Create response
var confirmRequest = new PreAuthRequest
{
    Operation = PreAuthOperation.Confirm,
    AuthorizationCode = createResponse.AuthorizationCode,  // e.g. "551437"
    OriginalTransactionDate = createResponse.AccountingDate,
    ReservationCode = createResponse.ReservationId  // optional
};

var confirmResult = connector.PreAuthAsync(confirmRequest);

La respuesta incluye Code, Message, AuthorizationCode y, de forma opcional, Amount, CommerceCode, TerminalId, ReceiptContent, entre otros. Revisa Code para confirmar el éxito. Los retornos están estandarizados para todas las operaciones de preautorización.

Recupera las preautorizaciones pendientes

Para listar las preautorizaciones pendientes, llama a la operación Pre-authorization con Operation = Retrieve. El TPV devuelve hasta 30 de las preautorizaciones pendientes más recientes. En la respuesta solo se completan los campos RealDate y PendingPreAuthorizations.

El objeto Filters es obligatorio para la operación Retrieve. Los campos de filtro individuales que aparecen abajo son opcionales y acotan los resultados:

Este ejemplo recupera las preautorizaciones pendientes creadas en un rango de fechas para cualquier marca:

var retrieveRequest = new PreAuthRequest
{
    Operation = PreAuthOperation.Retrieve,
    Filters = new PreAuthFilters
    {
        InitialDate = new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero),
        FinalDate = new DateTimeOffset(2026, 1, 2, 0, 0, 0, TimeSpan.Zero),
        CardBrand = 0
    }
};

var retrieveResult = connector.PreAuthAsync(retrieveRequest);

Cada elemento de la lista PendingPreAuthorizations incluye AuthorizationCode, TransactionDate, Amount, Last4Digits, EntryMode, CommerceCode, TerminalId, DateLimit (vencimiento), ReceiptCode y ReservationId. Usa estos valores para identificar una preautorización en un Confirm, Modify o Remove posterior. Para ver la lista completa de campos, consulta Métodos y parámetros.

Siguientes pasos

• Para el procesamiento de pagos estándar sin reserva de fondos, consulta la guía Pago en un solo paso.
• Para revertir o cancelar transacciones completadas, consulta la guía Reembolso.