Integración técnica
Material de ayuda · Zettle + Vende Fácil
Ver ayuda para cobro (TPV)

Configuración Zettle para el dueño de la tienda

En el panel: Payments SDK for Android (Bundle ID / app package y Client ID; Client Secret solo si el portal lo muestra), webhooks y, si lo necesita, OAuth Reader Connect (opcional, enlaces de lector vía API). El cobro con TDV va en la app nativa con el SDK; Vende Fácil expone API de conector (sobre cifrado, intent, payment-result).

Lector de tarjetas iZettle (referencia visual)

Referencia de hardware (modelo ilustrativo). Foto: Santeri Viinamäki, CC BY-SA 4.0, Wikimedia Commons.

Marca Zettle by PayPal

Marca de producto (referencia). Logo en Wikimedia Commons (dominio público según archivo).

Panorama

Para cobro con lector en Android use el Zettle Payments SDK en su APK. En Vende Fácil guarde el registro Payments SDK for Android del portal (como mínimo Bundle ID / app package y Client ID; el portal a menudo no muestra Client Secret — el login del SDK es OAuth con PKCE en el dispositivo). Si aplica, configure la signing key de webhooks Pusher. El conector VF (JWT VF-C04 y VF-C05) puede descargar un sobre cifrado con metadatos del SDK (y secret vacío si no hay), llama a prepare-sdk-payment y confirma con payment-result. Ese flujo no usa el TPV web como terminal de tarjeta. De forma opcional, si desea usar la API Reader Connect (reclamar códigos de lector, listar o desenlazar enlaces) desde el dashboard, configure otra aplicación OAuth en el portal Zettle, registre la redirect URI que muestra el panel, guarde Client ID/Secret en la misma sección Zettle y pulse Conectar cuenta Zettle; es independiente del cobro vía SDK.

Dos tipos de registro en el portal Zettle

En el Zettle Developer Portal existen flujos distintos (nombres según la interfaz en inglés). Reader Connect usa una app OAuth con Client ID y Client Secret en servidor. El registro Payments SDK for Android suele mostrar solo Client ID y app package; el SDK en el teléfono completa el login con PKCE.

  • Public API / app OAuth en servidor — «An app which will be made available for wide public use». Incluye OAuth Redirect URIs hacia su dominio. Sirve para integraciones de backend; en Vende Fácil encaja con el flujo Reader Connect (opcional): el panel muestra la redirect exacta (…/api/zettle/oauth/callback), guarda Client ID/Secret en la tienda y completa el consentimiento con Conectar cuenta Zettle.
  • Payments SDK for Android — «Integrate with our SDK and start taking payments». Los mismos conceptos de nombre, redirect y URL de app, más Bundle ID (en el portal; en Android es el identificador único de su APK: suele coincidir con el applicationId / paquete de Gradle). Sirve para registrar la app nativa que embebe el SDK; no sustituye el registro anterior si ambos conviven en su proyecto.

Si en el futuro Zettle le asigna un Client Secret al registro SDK, no debe mostrarse en claro: puede guardarse en el panel y la app lo recibe en sobre cifrado (RSA en Keystore o modo alternativo con VF-C05). Si no hay secret, el sobre lleva el campo vacío y el SDK sigue el flujo PKCE habitual.

Credenciales que debe crear (o registrar)

Portal Zettle + panel Vende Fácil + conector (APK).

QuéDónde se creaQué obtieneUso en Vende Fácil
1. Payments SDK for Android (portal Zettle)Developer Portal → registro SDK AndroidApp package / Bundle ID, Client ID (y Client Secret solo si el portal lo muestra)Se pegan en el panel de la tienda (sección Zettle). Lo que sea secreto se cifra; el APK obtiene el sobre vía POST /api/connector/zettle/sdk-envelope.
2. Webhook Pusher (opcional)Portal ZettleURL pública + signing keyEn el panel: URL del tipo …/api/webhooks/zettle/ID_DE_TIENDA y signing key. Se conservan igual que antes.
3. Conector VF (Android)Panel o login en la app conectorJWT conector + secreto HMAC (VF-C04 / VF-C05)API Vende Fácil: sobre SDK, prepare-sdk-payment, payment-result, acuse opcional sdk-config-ack.
4. OAuth Reader Connect (opcional)Portal Zettle — aplicación OAuth distinta del registro SDKClient ID, Client Secret; tras «Conectar cuenta», refresh en servidorPanel → Zettle → bloque Reader Connect: redirect URI, credenciales, Conectar cuenta Zettle; modal Enlazar lector. No sustituye al SDK para cobrar en la TDV.

Zettle Payments SDK for Android

El Bundle ID del portal debe coincidir con el applicationId de su APK. El cobro con lector sigue la documentación del SDK. El acceso del comercio a su cuenta Zettle/PayPal en el dispositivo ocurre dentro del flujo del SDK. El bloque OAuth Reader Connect del panel es solo para la API de enlaces de lector en servidor, no para sustituir al SDK en el cobro.

Qué configurar en Zettle (OAuth Redirect URI)

Según la guía oficial Create credentials for an SDK app:

  1. Entre en developer.zettle.com → Dashboard.
  2. Cree o edite credenciales de Payments SDK for Android (no mezclar con Reader Connect u otra app).
  3. En el campo OAuth Redirect URI, indique exactamente (sin https://, sin espacios al final, respetando mayúsculas y minúsculas):
    vfconnector://zettlepay
  4. Es el mismo tipo de URI que el ejemplo oficial del portal (awesomeapp://zettlelogin); no tiene por qué ser una URL https «pública» para el redirect nativo.
  5. Compruebe que el Client ID de esa credencial sea el mismo que guardó en el panel Vende Fácil (Client ID · Payments SDK for Android) y el que aparece en la URL de autorización al iniciar sesión en el conector (client_id=…). Si Zettle le dio otro Client ID tras corregir la app, actualice el panel. (Ejemplo de client_id visto en el navegador: 7bf08524-a947-42e3-a415-d00c42e5f041 — debe coincidir con el suyo.)
  6. El package name y la firma del APK del conector deben coincidir con lo declarado en el portal para esa credencial Android.
  7. Si las credenciales se crearon sin rellenar ese OAuth Redirect URI, o con otra cadena, Zettle mostrará un error del tipo Parameter redirect_uri contains an URI that is not allowed aunque el resto esté bien.

Prerrequisitos

1
Cuenta comercio Zettle activa y lector compatible, con red estable (WiFi recomendado según guía del fabricante).
2
En el portal: registro Payments SDK for Android alineado con su APK; en Vende Fácil: mismos datos en la sección Zettle del panel.
3
En Vende Fácil: permisos para editar Configuración de la tienda y entorno para probar la app Android con el SDK según su despliegue.

API conector (flujo SDK)

  1. Aprovisione el dispositivo (POST /api/connector/devices/auto-provision desde la app o token desde el panel). Guarde VF-C04 y VF-C05.
  2. Opcional: par RSA en Android Keystore y envíe módulo/exponente en POST /api/connector/zettle/sdk-envelope para recibir el payload del SDK cifrado (p. ej. clientSecret vacío si solo usa PKCE). Sin RSA, el servidor puede usar el modo PBKDF2 con VF-C05 (ver documentación técnica del proyecto).
  3. POST /api/connector/zettle/prepare-sdk-payment con orderId (pedido PENDING) y propina opcional → devuelve internalTraceId, importe en centavos, moneda y caducidad.
  4. Ejecute el cobro con el Payments SDK en el dispositivo; al terminar, POST /api/connector/payment-result con orderId, internalTraceId y cardPaymentUuid (firma HMAC del cuerpo si VF-C05 está configurado).
  5. Opcional: POST /api/connector/zettle/sdk-config-ack para acuse de versión de configuración.

Reader Connect (opcional)

Si no necesita reclamar lectores ni gestionar enlaces desde Vende Fácil, puede ignorar este bloque. Si sí: cree en el portal Zettle una aplicación OAuth adecuada para integración de servidor (no confundir con el registro Payments SDK for Android).

  1. En el portal Zettle, registre como redirect URI la URL exacta que muestra el panel bajo «Redirect URI» (típicamente {su dominio VF}/api/zettle/oauth/callback). Debe coincidir carácter a carácter con la que usa el servidor al intercambiar el código.
  2. En Configuración de la tienda → sección Zettle, pegue el OAuth Client ID y OAuth Client Secret de esa app y pulse Guardar cambios.
  3. Pulse Conectar cuenta Zettle: se abrirá el consentimiento en Zettle; al volver, el panel mostrará un mensaje de éxito o error.
  4. Use el modal Enlazar lector para reclamar códigos o desenlazar. Desconectar OAuth borra los tokens en el servidor pero conserva Client ID/Secret.

Referencia técnica: Reader Connect — enlazar lector y docs/ZETTLE_ANDROID_PHASE1_API.md (§4a).

Webhooks (Pusher)

Para notificaciones de eventos, configure en Zettle la URL de webhook que muestra el panel (forma típica …/api/webhooks/zettle/ID_DE_TIENDA) y pegue la Signing key en el campo correspondiente. Vacíe el campo solo si desea conservar el secreto ya guardado.

Pruebas: sin sandbox

Zettle no ofrece un entorno de pruebas paralelo comparable a un sandbox de pagos en línea. Los cobros suelen ser reales. Se recomienda importes mínimos (por ejemplo 1 peso) y luego anular o reembolsar según las opciones de su cuenta y las políticas de Zettle y de su banco.

Referencias útiles

Vende Fácil · Documento orientativo. Marcas citadas pertenecen a sus titulares.

Ayuda para quien cobra en TPV