Seguridad: autorizar una app en la lista de integradores

Lección 5 de 8

Curso Cobro a domicilio y SDK de FINORA Pago. Anterior: Sucursal de origen y conciliación.

Objetivo

Que tu app quede autorizada por el comercio para cobrar, anular o consultar el estado, y entender por qué una copia de tu app firmada con otra llave no puede cobrar.

Cómo te reconoce FINORA Pago

1. Android dice quién llama. FINORA Pago lee el paquete de la app que lo invocó. Ningún campo de la solicitud sirve para hacerse pasar por otra app.
2. Tu firma, en cada llamada. El certificado con que está firmada tu app debe coincidir con una huella SHA-256 autorizada por el comercio.
3. Cerrado por defecto. Sin lista, vacía o mal formada: ninguna app está autorizada.
4. Permisos por app. Acciones (COBRAR, REVERSAR, ESTADO), tope por cobro y sucursales permitidas.
5. Doble verificación. El servidor vuelve a comprobar paquete y huella al crear el cobro y al anularlo, y registra qué app creó cada venta.
6. Pantalla protegida. La pantalla de cobro ignora toques a través de ventanas superpuestas.
7. Sin datos de tarjeta. Tu app solo recibe últimos 4 dígitos y marca.

Pasos

1. Saca la huella del certificado que firma lo que se instala (no la del APK):

   apksigner verify --print-certs app-release.apk | grep SHA-256
   # o: keytool -list -v -keystore mi-llave.jks -alias mi-alias | grep SHA256
   # o: ./gradlew :app:signingReport

   Con Play App Signing, la que vale es la de Google: Play Console › Integridad de la app › Certificado de la llave de firma de apps. La app de ejemplo de FINORA muestra su propia huella en la cabecera.

2. Entrega al comercio tu applicationId, la huella (o las dos, si vas a rotar la llave), las acciones que necesitas, las sucursales y un tope razonable por cobro.

3. El comercio edita la lista en la consola de FINORA: Parámetros de aplicación de FINORA Pago para Android, parámetro «Apps integradoras autorizadas (SDK)» (grupo Integración), para todo el comercio o para un terminal.

   [
     {
       "paquete": "com.ejemplo.reparto",
       "huellas": ["<64 caracteres hexadecimales, con o sin dos puntos>"],
       "acciones": ["COBRAR", "REVERSAR", "ESTADO"],
       "montoMaximoCentavos": 5000000,
       "sucursales": ["CENTRO", "ESTE"]
     }
   ]

4. El terminal la recibe en su siguiente actualización de parámetros, o al pulsar «Revisar de nuevo» en FINORA Pago.

Las reglas que más fallan

Error	Resultado
Un espacio en la huella o en el paquete	Entrada inválida: no se recorta nada
huella como texto suelto en vez de huellas como lista	Entrada inválida
Raíz {"integradores": [...]} en vez de una lista	Ninguna app autorizada
acciones vacía, o "*" mezclado con otras	Entrada inválida
sucursales: []	Entrada inválida (para todas, omite el campo)
Más de 8000 caracteres	Ninguna app autorizada

Una entrada inválida se descarta sola: las demás siguen valiendo.

Baja y rotación

• Dar de baja una app es quitar su entrada: el servidor deja de aceptarla al instante y el terminal en su siguiente actualización de parámetros.
• Rotar la llave: entrega las dos huellas antes de publicar la versión nueva y retira la vieja cuando todos los equipos estén actualizados.
• La anulación del operador desde la pantalla de FINORA Pago y los reversos automáticos no exigen tu firma: el comercio manda sobre su terminal y el cliente siempre queda protegido.

Verificación

1. FinoraPago.estado(context).autorizado vale true (requiere la acción ESTADO).
2. Un cobro de demostración aprueba.
3. Instala una compilación de tu app firmada con otra llave: estado() responde autorizado = false y el cobro devuelve NO_AUTORIZADO sin crear nada.
4. Pide un monto por encima del tope: NO_AUTORIZADO con MONTO_FUERA_DE_LIMITE.

La clave de API no va en el teléfono

El SDK no usa la clave de API del comercio: tu identidad es tu firma. La clave de API solo existe en tu servidor, para el cobro en la nube y las consultas.

Siguiente: Lección 6 · Estados, EN_DUDA y anulaciones