Tap to Pay

Esta guía explica cómo integrar tu app Android con la app de Sipay Softpos (SoftPOS) mediante Android Intents, de forma App‑to‑App. En la práctica, tu app “lanza” Sipay Softpos con un Intent y un JSON que describe la operación (venta, reembolso, anulación, etc.). Sipay Softpos procesa el pago de forma segura en el dispositivo y te devuelve el resultado. Por qué te interesa:

Integración rápida: sin SDK pesado ni manejo de datos de tarjeta en tu app.
Menor coste de cumplimiento: la app de Sipay Softpos se encarga del cumplimiento EMV/PCI.
Mejor experiencia: cobros contactless directamente en el móvil del comercio.

¿Qué es un Android Intent App‑to‑App?

Es el mecanismo nativo de Android para pedir a otra app que realice una acción con unos datos. Tú defines una “acción” y envías un “payload” (JSON en String) a Sipay Softpos. Sipay Softpos muestra su UI, realiza el cobro y te devuelve el control con el resultado.

Ventajas

Seguridad: tu app no toca PAN ni PIN; lo gestiona Sipay Softpos.
Aislamiento: actualizaciones de Sipay Softpos no rompen tu app si mantienes el contrato del Intent.

Requisitos previos

Dispositivo Android con NFC y compatible con SoftPOS. App de Sipay Softpos instalada en el dispositivo. Manifest: declara la app de Sipay Softpos para que Android permita descubrirla:

<queries>
<package android:name="es.sipay.softpos" />
</queries>

nota

Sustituye com.Sipay Softpos.softpos.app por el package real de Sipay Softpos que uses en pruebas/producción.

Convenciones de formato:
- Cantidades en el payload como String con punto y dos decimales (ej.: "10.00"). Aunque en España usamos coma decimal, el JSON debe usar punto.
- Códigos de idioma de 2 letras (ej.: "es", "en").

Dispositivo

Dispositivo Android con NFC habilitado.
Almacén de claves respaldado por hardware, es decir, TEE en un SoC (Sistema en Chip).
Servicios de Google Mobile instalados.

Android OS

Android 8.1 o superior en producción.
La versión de Android debe tener soporte activo y parches de seguridad en los últimos seis meses.
No debe estar rooteado ni marcado como manipulado.

Sipay Softpos

Diseñado para funcionar solo en línea, es decir, con conexión a internet.
Las opciones de desarrollador deben estar siempre desactivadas.
Debe instalarse desde Google PlayStore.

App‑to‑App: Lanzar Sipay Softpos desde tu app Android

Paso 1. Construye el Intent

// Recomendado: usa el package de TU app para componer la acción y la clave del extra
// es.sipay.softpos
val myPackage = applicationContext.packageName
val intent = Intent("$myPackage.SOFTPOS")

// configJsonString: JSON en String con la operación y sus datos (ver ejemplos más abajo)
intent.putExtra("$myPackage.CONFIGURATION", configJsonString)

// Verifica que existe una app que pueda manejar este Intent (Sipay Softpos)
if (intent.resolveActivity(packageManager) != null) {
    startActivityForResult(intent, PHOS_REQUEST_CODE) // API tradicional
    // Alternativa moderna: registerForActivityResult con un ActivityResultContract personalizado
} else {
    // Manejo de error: Sipay Softpos no instalado
}

Paso 2. Estructura general del payload (JSON en String)

{
  "operation": "sale | refund | void | sso_login | history | receipt | language",
  "data": { /* campos específicos */ }
}

Paso 3. Operaciones soportadas y ejemplos

Ejemplo de venta

{
  "operation": "sale",
  "data": {
    "amount": "10.00",
    "tip": "2.00",
    "order_reference": "REF-123",
    "show_result": "true",
    "extras": {
      "channel": "INSTORE",
      "correlation_id": "c0ffee-123"
    }
  }
}

Ejemplo de devolución

{
  "operation": "refund",
  "data": {
    "transaction_id": "TX-20240801-0001",
    "amount": "5.00",
    "extras": {
      "reason": "Devolución parcial"
    }
  }
}

Ejemplo de anulación

{
  "operation": "void",
  "data": {
    "transaction_id": "TX-20240801-0001",
    "extras": {
      "user": "seller-42"
    }
  }
}

Paso 4. Recibir el resultado (onActivityResult)

App‑to‑App devuelve control a tu Activity.
Comportamiento típico:
resultCode: RESULT_OK | RESULT_CANCELED
data: Intent con extras (p. ej., status, response_code, transaction_id, message)

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == PHOS_REQUEST_CODE) {
        if (resultCode == Activity.RESULT_OK && data != null) {
            val status = data.getStringExtra("status")        // por confirmar clave exacta
            val responseCode = data.getStringExtra("code")    // por confirmar
            val transactionId = data.getStringExtra("tx_id")  // por confirmar
            // TODO: mapear estados, persistir, actualizar UI
        } else {
            // Cancelación por usuario o error
        }
    }
}

Buenas prácticas de integración

Verifica la disponibilidad de Sipay Softpos antes de lanzar el Intent; guía al usuario a instalarla si falta.
No registres datos sensibles en logs (emails/teléfonos de recibos, etc.).
Establece timeouts y reintentos idempotentes; usa order_reference y un correlation_id en extras.
Si usas SSO: tokens con TTL corto, firma asimétrica (p. ej. RS256), rotación de claves.
Internacionalización: cambia el idioma de Sipay Softpos vía operación language cuando tu app cambie de idioma.

Pruebas recomendadas

Ventas aprobadas/denegadas (fondos insuficientes, tarjeta expirada, PIN incorrecto).
Propina: con y sin tip; reglas de redondeo.
Void inmediato vs refund diferido.
Envío de recibos vía email/SMS.
Web‑to‑App: valida notificaciones backend y estados en tiempo real.
Rendimiento: tiempos de autorización y de UI.

Checklist rápido:

App de Sipay Softpos instalada y discoverable (resolveActivity).
JSON válido con punto decimal en importes.
Manejo de RESULT_OK/RESULT_CANCELED.
Persistencia de transaction_id y response_code.
Reintentos idempotentes con order_reference.

FAQ

¿Necesito permisos especiales? No, salvo declarar el package de Sipay Softpos en <queries> del manifest.
¿Mi app verá datos de tarjeta? No. Sipay Softpos gestiona EMV/PCI.
¿Puedo usar coma decimal? En pantalla sí, pero en el JSON usa punto y dos decimales.
¿Hay callback en Web‑to‑App? No. Usa notificaciones de backend.

Preguntas para terminar tu integración con éxito

Compártenos esta información para adaptar la guía a tu caso y validar en preproducción/producción:

Identificadores técnicos

PackageName de tu app Android (prod y preprod).
PackageName exacto de Sipay Softpos que instalarás (prod y preprod).
¿Confirmas uso de action "<tuPackage>.SOFTPOS" y extra "<tuPackage>.CONFIGURATION"?

Contrato de respuesta

¿Qué claves de respuesta necesitas que validemos en onActivityResult? (transaction_id, status, response_code, message).
¿Quieres un esquema de errores y ejemplos JSON en la doc?

Autenticación y SSO

¿Usarás SSO desde el inicio? issuer, formato y caducidad del token.
¿Endpoint/backend para emitir y validar tokens listo?

Reglas de negocio

¿Habrá propina? Reglas de redondeo e importe máximo.
¿Permitirás refund parcial? ¿Ventanas temporales para void vs refund?
Moneda: ¿solo EUR o multi‑moneda?

Recibos y marca

¿Envío de recibos lo hará Sipay Softpos directamente o quieres pasar por tu pasarela?
¿Branding (logo/textos) personalizable?

Web‑to‑App

¿Usarás Web‑to‑App? Confirma el flujo de notificaciones servidor‑a‑servidor.

Operativa y soporte

Datos de contacto de soporte técnico, horarios, y acuerdos de nivel de servicio (SLA).

¿Qué es un Android Intent App‑to‑App?​

Requisitos previos​

Dispositivo​

Android OS​

Sipay Softpos​

App‑to‑App: Lanzar Sipay Softpos desde tu app Android​

Paso 1. Construye el Intent​

Paso 2. Estructura general del payload (JSON en String)​

Paso 3. Operaciones soportadas y ejemplos​

Paso 4. Recibir el resultado (onActivityResult)​

Buenas prácticas de integración​

Pruebas recomendadas​

FAQ​

Preguntas para terminar tu integración con éxito​