Saltar al contenido principal

De cero a tu primer cobro

Beta

SDK 1.0.0-beta.3 y FINORA Pago 0.16.0 en su variante de demostración. Los cobros de este tutorial son simulados (simulado = true) y no mueven dinero. No uses el SDK con dinero real hasta que esta sección diga «Disponible».

En este tutorial pasas de nada a un cobro aprobado y anulado, en este orden: primero con la app de ejemplo de FINORA (para comprobar que el equipo y la lista de integradores están bien) y después con tu propia app. Calcula unos 30 minutos.

Lo que necesitas​

PiezaQuién la da
Un teléfono Android 6.0 o superiorTú
FINORA Pago 0.16.0, variante de demostración (com.dcgeeks.finora.pago.demo)FINORA, bajo acuerdo
Un comercio de pruebas con un terminal y al menos una sucursal (por ejemplo CENTRO)FINORA
La app de ejemplo Reparto de ejemplo (com.dcgeeks.finora.pago.ejemplo)FINORA, bajo acuerdo
Android Studio y un proyecto Kotlin con minSdk 23 o superiorTú
Alguien con acceso a la consola del comercio para editar la lista de integradoresEl comercio (o FINORA en el comercio de pruebas)

Paso 1. Enrola FINORA Pago​

  1. Instala FINORA Pago (variante de demostración) en el teléfono.
  2. Ábrelo y enrólalo en el comercio de pruebas con el código que te entregue FINORA.
  3. Comprueba que la pantalla principal dice que está en línea. Si usas un lector Bluetooth, vincúlalo desde FINORA Pago; con el lector simulado no hace falta.

Paso 2. Prueba con la app de ejemplo​

La app de ejemplo usa solo la API pública del SDK. Si ella cobra, el equipo, el servidor y la lista están bien, y cualquier fallo posterior estará en tu app.

  1. Instala Reparto de ejemplo. En su cabecera verás la huella SHA-256 de su certificado y el estado «No autorizado».

  2. Pide al comercio (en el de pruebas, a FINORA) que agregue esta entrada a la lista de integradores. La edita en la consola: Parámetros de aplicación › FINORA Pago para Android › Apps integradoras autorizadas (SDK), grupo Integración (ver Seguridad y alta):

    [{"paquete": "com.dcgeeks.finora.pago.ejemplo", "huellas": ["<la huella que muestra la app>"], "acciones": ["*"]}]

  3. En FINORA Pago pulsa «Revisar de nuevo». La app de ejemplo debe pasar a «Autorizado».

  4. Pulsa «Preparar lector» (opcional): la app muestra cuántos milisegundos tardó el lector en quedar listo.

  5. Pulsa «Cobrar» en un pedido. FINORA Pago abre su pantalla, cobra y vuelve: el pedido queda pagado con últimos 4, marca y autorización.

  6. Pulsa «Anular»: el pedido queda anulado.

Si algo falla aquí, mira la tabla de problemas frecuentes antes de seguir.

Paso 3. Agrega el SDK a tu app​

settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://developers.finoracore.com/maven/")   // FINORA Pago SDK
    }
}
app/build.gradle.kts
dependencies {
    implementation("com.dcgeeks.finora:pago-sdk:1.0.0-beta.3")
}

Sincroniza Gradle. El SDK trae sus <queries> de Android 11 y sus reglas de R8.

Paso 4. Da de alta tu app​

  1. Saca la huella del certificado con que firmas lo que vas a instalar:

    ./gradlew :app:signingReport            # para la variante debug, la llave de depuración de tu equipo
    # o, sobre el APK firmado:
    apksigner verify --print-certs app-release.apk | grep SHA-256

  2. Pide al comercio una entrada nueva en la lista, al lado de la de la app de ejemplo, con tu applicationId, tu huella, las acciones y las sucursales:

    {"paquete": "com.tuempresa.reparto", "huellas": ["<tu huella>"], "acciones": ["COBRAR", "REVERSAR", "ESTADO"], "sucursales": ["CENTRO"]}

  3. En FINORA Pago, «Revisar de nuevo».

Paso 5. Escribe el cobro​

class PedidoActivity : ComponentActivity() {

    // Variante de demostración: no mueve dinero. Quita el argumento para la variante de producción.
    private val cobrar = registerForActivityResult(FinoraPago.Cobrar(Contrato.PAQUETE_DEMO)) { r ->
        when {
            r.aprobada -> marcarPagado(r.referenciaExterna, r.referenciaFinora, r.autorizacion, r.ultimos4, r.marca)
            r.estado.requiereConsulta -> marcarEnDuda(r.referenciaExterna, r.referenciaFinora)   // nunca cobres otra vez
            else -> mostrar("${r.estado}: ${r.mensaje}")
        }
    }

    private val anular = registerForActivityResult(FinoraPago.Reversar(Contrato.PAQUETE_DEMO)) { r ->
        if (r.anulada) marcarAnulado(r.referenciaExterna) else mostrar("${r.estado}: ${r.mensaje}")
    }

    fun alPulsarCobrar() = cobrar.launch(
        SolicitudCobro.Builder()
            .montoCentavos(12_500).moneda("VES")
            .referenciaExterna("PED-1001")
            .sucursalCodigo("CENTRO")
            .build()
    )

    fun alPulsarAnular() = anular.launch(
        SolicitudReverso.Builder()
            .referenciaExterna("PED-1001").montoCentavos(12_500)
            .claveIdempotencia("PED-1001-ANU")
            .build()
    )
}

Antes de mostrar el botón «Cobrar», puedes comprobar el estado (fuera del hilo principal):

val e = FinoraPago.estado(context)   // instalado, autorizado, listo, motivo, medios, lectorListo

Paso 6. Comprueba los cinco resultados​

HacesDebes ver
FinoraPago.estado(context)instalado, autorizado y listo en true
Cobrar PED-1001APROBADA con simulado = true, referenciaFinora y sucursalCodigo = CENTRO
Cobrar otra vez PED-1001La misma APROBADA, sin que se lea la tarjeta
Anular con PED-1001-ANUANULADA
Cobrar otra vez PED-1001CONFLICTO con REFERENCIA_USADA: el siguiente intento lleva PED-1001-2

Si los cinco coinciden, tu integración funciona. Antes de salir a producción lee Estados y errores (el caso EN_DUDA) y Sucursal y conciliación.

Problemas frecuentes​

VesCausa probableSolución
NO_INSTALADOApuntas a la variante equivocadaCon la variante de demostración usa FinoraPago.Cobrar(Contrato.PAQUETE_DEMO)
autorizado = false o NO_AUTORIZADOLa huella no es la del certificado instalado, tiene espacios, o falta «Revisar de nuevo»Copia la huella de signingReport o apksigner, sin espacios, y revisa de nuevo
NO_AUTORIZADO solo en estado()Tu entrada no tiene la acción ESTADOPide ESTADO o usa ["*"]
PETICION_INVALIDA con SUCURSAL_INVALIDALa sucursal no existe o no es del comercio; los códigos distinguen mayúsculasUsa el código exacto de la tienda en FINORA
NO_LISTO con MERCHANT_SIN_SOPORTEEl servidor del entorno no admite cobros del SDKAvisa a FINORA
NO_AUTORIZADO al llamar con un Intent propioLo lanzaste con startActivityUsa startActivityForResult o el contrato del SDK

Siguiente paso​