Crear un pago preautorizado

Las transacciones de preautorización le permiten verificar la validez de la tarjeta y reservar fondos sin una captura inmediata. Este es un proceso de dos pasos: crear la preautorización y confirmarla más tarde (capturar los fondos).

Esta guía le explica cómo crear preautorizaciones, almacenar referencias de transacciones y confirmar (capturar) los fondos reservados.

Requisitos

Antes de comenzar, asegúrese de tener:

• Permiso de preautorización habilitado en su cuenta de comercio (código de servicio 100101 o 100201)
• SDK inicializado con entorno y licencia a través de CommonUtils
• PIN pad conectado e inicializado (recibió PinpadConfig de onInitFinished)
• Delegados implementados: RedsysDelegateGeneric, RedsysBTPinpadInitDelegate, RedsysBTPinpadPaymentDelegate

Proceso de preautorización

Paso 1: Crear la preautorización

Para iniciar una preautorización, use el método payWithPinpadBluetooth con un PagoDTO configurado para el tipo de preautorización.

Configurar el PagoDTO

Cree el DTO de pago y establezca el tipo de transacción en PREAUTORIZACION:

// Importar vía Bridging Header: PagoDTO.h
func createPreauthorization() {
    let amount: Float = 150.00  // Monto máximo a reservar

    // Inicializar PagoDTO con monto en céntimos
    let pagoDTO = PagoDTO(
        valor: Int(amount * 100),  // 15000 céntimos = €150.00
        mMoneda: 978,              // Código de moneda ISO 4217 (978 = EUR)
        nFactura: "PREAUTH001",    // Número de factura único
        email: "",
        tlfCliente: "",
        datosPropietarios: ""
    )

    // Establecer tipo de transacción a Preautorización
    pagoDTO.setTipoPago("PREAUTORIZACION")

    // Ejecutar la preautorización
    executePreauth(pagoDTO)
}

Ejecutar Preautorización

Use el mismo método payWithPinpadBluetooth que para los pagos regulares:

func executePreauth(_ pagoDTO: PagoDTO) {
    // Crear MerchanDTO con campos requeridos
    let merchantDTO = MerchanDTO()
    merchantDTO.fuc = "999008881"
    merchantDTO.fucExtendido = "999008881"
    merchantDTO.terminal = "001"
    merchantDTO.password = "merchant_pass"

    // Ejecutar preautorización
    pinpadManager.payWithPinpadBluetooth(
        selectedDevice,
        merchan: merchantDTO,
        config: pinpadConfig,
        andPagoDTO: pagoDTO,
        withDelegate: self
    )
}

El SDK maneja la lectura de la tarjeta, la entrada del PIN y la comunicación con la pasarela. El cliente debe presentar su tarjeta para establecer la reserva de fondos.

Paso 2: Almacenar referencias de transacción

Cuando la preautorización es exitosa, el delegado onPaymentFinished recibe un RespuestaTransaccionDTO. Debe almacenar el identificadorRTS para confirmar la operación más tarde:

func onPaymentFinished(_ result: RespuestaTransaccionDTO!, orError error: Error!) {
    if let transaction = result, error == nil {
        // Verificar estado de la transacción
        if transaction.estado == "F" {  // F = Finalizada
            if transaction.resultado == "Autorizada" {
                // Preautorización exitosa
                let rtsID = transaction.identificadorRTS ?? ""
                print("Pre-auth exitosa. ID RTS: \(rtsID)")

                // Almacenar ID RTS para confirmación posterior
                savePreAuthReference(rtsID: rtsID, forBooking: bookingID)
            }
        }
    } else {
        print("Preautorización fallida: \(error?.localizedDescription ?? "")")
    }
}

El identificadorRTS es una cadena de 24 caracteres que identifica de forma única la transacción de preautorización. Este ID es requerido para confirmar o cancelar la transacción más tarde.

Paso 3: Confirmar la preautorización

Para capturar los fondos, realice una operación de confirmación. Esto requiere el identificadorRTS original del Paso 2.

Consultar y Confirmar Usando Filtros

El SDK usa filtros de consulta para gestionar las confirmaciones:

// Importar vía Bridging Header: ConsultaFechasDTOFiltros.h, RedsysTransactionManager.h
func confirmPreauthorization(rtsID: String) {
    // Crear filtro para operaciones de confirmación
    let filtros = ConsultaFechasDTOFiltros()
    filtros.setTipoOperacion("CONFIRMACION")

    // Crear DTO de consulta con el identificador RTS
    let consulta = ConsultaFechasDTO()
    // Configurar consulta con datos del terminal e ID RTS

    // Ejecutar consulta de confirmación
    RedsysTransactionManager.peticionConsultaFechaPagina(
        consulta,
        conValores: filtros.dictValores()
    ) { result, error in
        if let operations = result, error == nil {
            // Procesar resultado de confirmación
            print("Confirmación procesada")
        } else {
            print("Confirmación fallida: \(error?.localizedDescription ?? "")")
        }
    }
}

La confirmación captura los fondos reservados. El monto final puede ser menor o igual al monto originalmente preautorizado. Si captura menos, los fondos restantes se liberan de nuevo al saldo disponible del cliente.

Paso 4: Cancelar una preautorización (opcional)

Si el servicio se cancela y desea liberar los fondos reservados inmediatamente, realice una cancelación. Las preautorizaciones que no se confirman caducan automáticamente después de su período de validez (típicamente 7 días), pero la cancelación explícita proporciona una liberación inmediata de fondos.

Use el filtro de consulta con el tipo PREAUTORIZACION para identificar y cancelar la transacción específica usando el identificadorRTS almacenado.

Restricciones técnicas clave

Mejores prácticas

Almacenar Referencias de Transacción

Guarde el identificadorRTS en su base de datos indexado por referencia de reserva o servicio:

func savePreAuthReference(rtsID: String, forBooking bookingID: String) {
    // Vincular ID RTS al registro de reserva
    database.save(rtsID: rtsID, bookingID: bookingID, expiration: Date().addingTimeInterval(7*24*60*60))
}

Implementar Seguimiento de Caducidad

Monitoree las preautorizaciones que se acercan a su expiración e indique al personal que las finalice o cancele antes de que ocurra la expiración automática.

Comunicar con los Clientes

Explique claramente a los clientes cuándo se realizan las preautorizaciones y cuándo se finalizarán para reducir la confusión sobre cargos pendientes en sus estados de cuenta.

Solución de problemas

Comercio No Habilitado para Preautorizaciones

Si recibe el error “El comercio no tiene habilitada la operativa de Preautorizaciones”, contacte al soporte de Get Mini para habilitar los permisos de preautorización en su cuenta de comercio.

Preautorización Caducada

Si la confirmación falla con errores de expiración, la preautorización excedió su período de validez. Procese una nueva venta por el monto real del cargo.

Límite de Confirmación Excedido

El error “No es posible realizar más confirmaciones sobre la preautorización original” significa que ya ha capturado el máximo de confirmaciones permitidas. Verifique su historial de transacciones para intentos de confirmación previos.

Desajuste de Moneda

La moneda en la confirmación debe coincidir con la moneda de la preautorización original. Verifique que ambas transacciones usen el mismo código de moneda ISO 4217.

Próximos pasos

Explore operaciones de pago relacionadas:

• Crear una venta - Transacciones de venta estándar
• Ciclo de vida de la transacción - Entender las fases de procesamiento de transacciones
• Seguridad y licencias - Aprender sobre seguridad de pagos