Anular un cobro

Beta

Contrato v1 del SDK 1.0.0-beta.3 (FINORA Pago 0.16.0). Desplegado en Beta: todavía no lo uses con dinero real.

Tu app puede anular un cobro que ella misma aprobó en ese mismo equipo, mientras el lote del terminal siga abierto. Es el mismo reverso que hace FINORA Pago desde su pantalla: llega al autorizador por la cola persistente del terminal, que lo reintenta si no hay red.

private val anular = registerForActivityResult(FinoraPago.Reversar()) { r: ResultadoReverso ->
    when (r.estado) {
        EstadoReverso.ANULADA -> marcarAnulado(r.referenciaExterna)
        EstadoReverso.PENDIENTE, EstadoReverso.SIN_RESPUESTA -> reintentarLuego()   // con la MISMA clave
        EstadoReverso.NO_ANULABLE -> mostrar("No se puede anular aquí: ${r.codigo}")
        else -> mostrar(r.mensaje)
    }
}

anular.launch(
    SolicitudReverso.Builder()
        .referenciaExterna("PED-1001")        // la del cobro aprobado
        .montoCentavos(12_500)                // el de la venta
        .claveIdempotencia("PED-1001-ANU")    // la misma en cada reintento de esta anulación
        .motivo("Pedido devuelto")            // opcional
        .build()
)

Método	Extra	Regla
referenciaExterna	finora.referencia_externa	La del cobro aprobado
montoCentavos	finora.monto_centavos	El monto de la venta; si no coincide, NO_ANULABLE
claveIdempotencia	finora.clave_idempotencia	Letras, dígitos y . _ : -, de 1 a 64; distinta de la referencia del cobro
motivo	finora.motivo	Hasta 140 caracteres. Se guarda en tu lado; hoy no viaja al autorizador

La acción del Intent es com.dcgeeks.finora.pago.action.SDK_REVERSAR. Tu app debe estar autorizada para REVERSAR en la lista del comercio.

Control del integrador en el servidor

FINORA Pago envía con la anulación tu paquete y tu huella, y tu referenciaExterna. Si el cobro original lo creó una app integradora, el servidor exige que la anulación venga de esa misma app y que siga autorizada para REVERSAR en la lista del comercio. Si no, la rechaza con INTEGRADOR_NO_AUTORIZADO sin enviar el reverso al autorizador: tu app recibirá NO_AUTORIZADO y la venta seguirá vigente.

Una anulación pedida con SDK_REVERSAR siempre lleva tu paquete y tu huella.

Los reversos automáticos que FINORA Pago hace por su cuenta no pasan nunca por este control: protegen al cliente y salen siempre. Son cuatro, y se reconocen por su motivo exacto:

Motivo	Cuándo
TIMEOUT	La autorización quedó sin respuesta
ERROR_COMUNICACION	La autorización pudo llegar y no hubo respuesta legible
TARJETA_DECLINO	El emisor aprobó, pero la tarjeta rechazó la operación al cerrarla
CIERRE_EMV_FALLIDO	El emisor aprobó, pero el cierre con la tarjeta no se completó

Anulación desde la pantalla de FINORA Pago

El operador del comercio puede anular desde el propio equipo (la pantalla de FINORA Pago o la Caja de FINORA en el mismo terminal) una venta que cobró tu app. Está permitido: el comercio manda sobre su terminal. Esa anulación viaja sin tu paquete ni tu huella, con el motivo ANULACION_OPERADOR, y el servidor la acepta aunque el cobro lo haya creado tu app y la deja registrada en la bitácora de la intención.

Para tu app la venta queda anulada igual: si consultas la intención por su referenciaFinora, la verás anulada. No cuentes con que todas las anulaciones de tus ventas pasen por SDK_REVERSAR.

Estados

estado	Significado	Qué hacer
ANULADA	El autorizador aceptó: la venta sale del lote	Listo
PENDIENTE	La anulación está en cola sin respuesta: todavía no está anulada	Repite más tarde con la misma clave
RECHAZADA	El autorizador respondió que no: la venta sigue vigente	Gestiona una devolución con el comercio
NO_ANULABLE	No se intentó. Mira codigo: ORDEN_NO_COBRADA_AQUI, MONTO_NO_COINCIDE, REGISTRO_INCOMPLETO, LOTE_CERRADO	Con el lote cerrado corresponde una devolución
CONFLICTO	La clave de idempotencia ya se usó para otra venta	Usa otra clave
NO_AUTORIZADO	Tu app no tiene la acción REVERSAR, o el servidor respondió INTEGRADOR_NO_AUTORIZADO. La venta sigue vigente	Pide el permiso al comercio
PETICION_INVALIDA, NO_LISTO, OCUPADO	Como en el cobro
SIN_RESPUESTA (solo SDK)	No se sabe si salió	Repite con la misma clave
NO_INSTALADO (solo SDK)	FINORA Pago no está instalado

Solo ANULADA te autoriza a dar la venta por deshecha. Una app no puede anular ventas de otra app, aunque conozca su referencia.

Después de una anulación, la misma referenciaExterna no vuelve a cobrar (REFERENCIA_USADA): si el cliente vuelve a comprar, usa una referencia nueva.