Estados del cobro, EN_DUDA y anulaciones

Lección 6 de 8

Curso Cobro a domicilio y SDK de FINORA Pago. Anterior: Autorizar una app en la lista de integradores.

Objetivo

Decidir qué hace tu app con cada resultado, resolver un cobro en duda sin cobrar dos veces y anular un cobro aprobado.

La regla de oro

Solo APROBADA autoriza a entregar. EN_DUDA y SIN_RESPUESTA no son rechazos: el emisor pudo aprobar. Decide siempre por estado (y codigoRespuesta), nunca por el texto de mensaje.

Los estados en una tabla

estado	¿Hubo dinero?	Qué hace tu app
APROBADA	Sí	Entrega. Si es una repetición con estadoVerificado = false, consulta antes
RECHAZADA	No	Muestra el motivo; si el cliente reintenta, referencia nueva
EN_DUDA, SIN_RESPUESTA	Posible	No cobres otra vez. Repite con la misma referencia o consulta
CANCELADA	No	Con referenciaFinora, referencia nueva; sin ella, la misma
NO_COBRADA	No	No se leyó la tarjeta: reintenta con la misma referencia
OCUPADO	No	FINORA Pago atiende otro cobro: espera y reintenta igual
NO_LISTO, NO_AUTORIZADO, PETICION_INVALIDA	No	Corrige la causa (código)
CONFLICTO	No	Referencia ya usada con otro monto o ya terminada: usa otra
NO_INSTALADO	No	Pide instalar o actualizar FINORA Pago

Pasos: salir de EN_DUDA

1. Bloquea el botón «Cobrar» de ese pedido y avisa al motorizado: «No cobres otra vez».
2. Repite la solicitud con la misma referenciaExterna. Es seguro: FINORA Pago no vuelve a leer la tarjeta, te repite lo que sabe y, si el veredicto aprobado llegó después, lo verifica con el servidor antes de responder.
3. O consulta desde tu servidor por referenciaFinora en la API de pagos (con la clave de API, nunca desde la app).
4. Decide: pagada → entrega; no pagada → cobro nuevo con referencia nueva; sin resolver → espera y vuelve a consultar, o anula.

flowchart TD
    A[EN_DUDA o SIN_RESPUESTA] --> B{¿Tienes referenciaFinora?}
    B -- Sí --> C[Tu servidor consulta la venta]
    B -- No --> D[Repite con la MISMA referencia]
    D --> E[FINORA Pago devuelve lo que sabe]
    C --> F{¿Pagada?}
    F -- Sí --> G[Entrega]
    F -- No --> H[Cobro nuevo, referencia nueva]
    F -- Sin resolver --> I[Espera y consulta, o anula]

Pasos: anular un cobro

Tu app anula un cobro que ella misma aprobó en ese mismo teléfono, mientras el lote siga abierto.

private val anular = registerForActivityResult(FinoraPago.Reversar()) { r ->
    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")   // estable en cada reintento
        .motivo("Pedido devuelto")
        .build()
)

estado	Significado
ANULADA	La venta sale del lote. Solo este estado da la venta por deshecha
PENDIENTE	En cola sin respuesta: todavía no está anulada. Repite con la misma clave
RECHAZADA	El autorizador dijo que no: la venta sigue vigente
NO_ANULABLE	LOTE_CERRADO, MONTO_NO_COINCIDE, ORDEN_NO_COBRADA_AQUI…: con el lote cerrado corresponde una devolución
NO_AUTORIZADO	Tu app no tiene REVERSAR, o la venta la creó otra app

El operador del comercio también puede anular desde la pantalla de FINORA Pago. Esa anulación no pasa por tu app: no cuentes con que todas tus anulaciones lleguen por SDK_REVERSAR, y consulta la venta si necesitas saberlo.

Ejemplo

Acción	Resultado esperado
Cobrar PED-1001	APROBADA
Repetir PED-1001	La misma APROBADA, sin leer la tarjeta (estadoVerificado = true)
Anular con PED-1001-ANU	ANULADA
Repetir la anulación con PED-1001-ANU	El mismo resultado, sin un segundo reverso
Cobrar otra vez PED-1001	CONFLICTO · REFERENCIA_USADA: usa PED-1001-2

Verificación

Haz la tabla del ejemplo con la variante de demostración y comprueba cada resultado. Después, en el portal del comercio, abre la venta con «Ver»: su línea de tiempo muestra el cobro y la anulación.

Siguiente: Lección 7 · Tarjeta FINORA por NFC