Si la API PinPad de Clip Total 3 no muestra el cobro, no envíes otra solicitud de inmediato. Primero comprueba que el aplicativo PinPad esté instalado y abierto en la terminal, que el equipo esté asociado a la cuenta correcta y que GET /f2f/pinpad/v1/devices/status lo reporte como active. Una respuesta correcta de POST /f2f/pinpad/v1/payment indica que se creó una intención de pago; no demuestra por sí sola que el cliente haya pagado. Consulta el resultado por pinpadRequestId antes de repetir el intento.
Este diagnóstico está dirigido a negocios y equipos de desarrollo en México que conectan un sistema propio de ventas con Clip Total 3 mediante la API REST de PinPad. Es distinto del cobro normal tecleado en la terminal: una Total 3 puede aceptar cobros manuales y, aun así, no estar preparada para recibir órdenes de pago desde un software externo. La documentación oficial de Clip Developers confirma que la integración requiere un backend, credenciales, verificación de identidad y el aplicativo PinPad instalado.
El objetivo es separar cuatro situaciones: un equipo sin aprovisionar, una terminal registrada pero no disponible, una solicitud aceptada sin resultado conocido y una venta realmente aprobada. Confundirlas puede generar reintentos innecesarios, incidencias de caja y experiencias deficientes para el comprador. La guía no presume acceso a una terminal de prueba ni sustituye la verificación en tu propia cuenta.
Por qué la API puede responder y la pantalla seguir sin cobrar
La integración une dos componentes diferentes. Tu aplicación genera una intención de pago por el endpoint POST /f2f/pinpad/v1/payment, mientras el aplicativo PinPad instalado en la Total 3 debe estar habilitado y disponible para recibirla. Después, el cliente realiza la operación con su tarjeta y tu sistema necesita consultar el desenlace. Son etapas separadas; una petición HTTP aceptada no equivale a una transacción completada.
Clip especifica que su API PinPad es compatible con Total 3, Ultra, Clip PinPad y Stand 2. Pero esa compatibilidad de modelo no instala automáticamente la aplicación requerida en todas las unidades. En un caso documentado en el foro oficial de desarrolladores, el equipo de Clip confirmó que debía desplegar remotamente la aplicación y vincularla al número de serie. Es evidencia sobre ese caso concreto, no garantía de que todos los fallos tengan la misma causa.
Comprobaciones antes de programar o enviar otro cobro
- Identifica el modo de operación. Cobrar manualmente desde la interfaz habitual de Total 3 no prueba que esté instalada la aplicación específica para la API PinPad. Si sólo quieres usar las funciones nativas, consulta cómo funciona Clip Total 3 sin integración externa.
- Revisa la elegibilidad. Clip pide cuenta activa, identidad verificada (KYC), credenciales para API y un backend propio. El proveedor debe confirmar cualquier habilitación adicional que aplique a tu comercio.
- Comprueba el aprovisionamiento. Confirma con Clip que la aplicación PinPad fue asignada a tu número de serie. No presupongas que instalar aplicaciones manualmente o modificar el firmware sea una alternativa autorizada.
- Comprueba red y sesión. La terminal debe estar encendida, con internet y la aplicación PinPad abierta con la cuenta autorizada. Durante el aprovisionamiento remoto, el equipo de Clip pide mantener conexión Wi-Fi estable.
- Cuida el entorno de producción. Clip indica que esta API opera únicamente en producción. No la trates como un sandbox ni realices cargos con tarjetas reales para experimentar sin un procedimiento controlado y autorizado.
Si lo que falla es la conexión general del dispositivo, primero revisa Wi-Fi y SIM de Clip Total 3. Para la integración API, sin embargo, no basta con ver un icono de señal: también debe estar activo el aplicativo específico.
Matriz de diagnóstico: qué significa cada resultado
| Lo que observas | Interpretación prudente | Siguiente comprobación |
|---|---|---|
GET /devices/status devuelve [] | No hay dispositivos registrados en la respuesta o el filtro no coincide; no demuestra por sí solo daño físico. | Verificar serial, comercio, filtro y aprovisionamiento del aplicativo con Clip. |
El lector figura inactive o expired | No hay disponibilidad vigente para recibir una nueva intención; puede ser un problema de sesión, conexión o estado. | Confirmar que el aplicativo está abierto, la terminal despierta y la conexión estable. |
El lector figura active, pero la orden no se muestra | La disponibilidad reportada no confirma que esa solicitud haya llegado y terminado. | Revisar serial indicado, referencia de orden, pinpadRequestId y consulta del pago. |
| El POST devuelve un identificador de intención | La petición se registró; no equivale a aprobación bancaria. | Consultar el detalle antes de reintentar el mismo pedido. |
| El POST devuelve error por dispositivo no disponible | El equipo no pudo aceptar una intención nueva en ese momento. | Consultar el Health Check y esperar a que termine otro cobro o se abra la aplicación. |
La referencia oficial del endpoint de estado documenta active, inactive, expired y unknown, además de respuestas vacías. El estado unknown puede relacionarse con una función deshabilitada para el comercio: merece confirmación de Clip, no una modificación improvisada de credenciales. La tabla es una guía de diagnóstico editorial, no un mensaje literal del sistema para cada situación.
Procedimiento seguro cuando el cobro no aparece
1. Conserva la solicitud original
Guarda en un registro interno la referencia de tu pedido, la hora, el serial al que apuntaste, el resultado HTTP y el pinpad_request_id si la API lo devolvió. En una integración real, registra identificadores sin copiar secretos de autorización ni información completa de tarjetas. El comercio debe poder relacionar un intento con una sola venta.
2. Pregunta primero por la disponibilidad del dispositivo
Consulta GET /f2f/pinpad/v1/devices/status desde tu backend autorizado. Confirma que el serial recibido coincide con la Total 3 que está frente al cliente y que el estado sea active. Según el Health Check de Clip, una terminal puede considerarse no disponible si el aplicativo está cerrado, el equipo está bloqueado o hay un cobro en curso. Que esté ocupada no es necesariamente una avería.
3. Si la lista está vacía, separa falta de registro de falta de red
La respuesta [] admite varias explicaciones. Revisa filtros de consulta, relación entre credenciales y comercio, serial y la instalación de PinPad. En un hilo oficial de soporte relativo específicamente a Total 3, Clip indicó que el registro se activaba después del despliegue remoto y del primer inicio de sesión exitoso en el aplicativo. No concluyas automáticamente que debes reemplazar la terminal ni afirmes que la API está caída sin comprobar estos requisitos.
4. Comprueba la app de PinPad en pantalla
Si la app no está instalada, solicita la habilitación mediante el canal indicado en la guía de integración. Si está instalada, verifica sesión y que se mantenga abierta: Clip aclara que esta aplicación debe permanecer en pantalla para el procesamiento continuo de pagos por API. No confundas la pantalla principal de la terminal con la pantalla de la app PinPad.
5. Revisa el estado de la intención antes de reenviarla
Cuando el POST fue aceptado y recibiste pinpad_request_id, utiliza GET /f2f/pinpad/v1/payment?pinpadRequestId=... para consultar ese intento. El endpoint permite solicitar detalle adicional con Pinpad-Include-Detail: true. Distingue una solicitud registrada de un resultado aprobado y revisa si existen transacciones relacionadas antes de permitir un segundo cobro por la misma orden. Consulta la especificación de consulta de pagos para los campos vigentes.
6. Si necesitas cancelar una intención, comprueba primero su situación
Clip documenta un endpoint para eliminar una intención por su ID, pero advierte que la eliminación funciona únicamente mientras la terminal todavía no haya recogido la solicitud. No es lo mismo que devolver una compra ya aprobada. Por ello, no uses la eliminación de intención como si fuera un reembolso y no generes un nuevo POST sin conocer el resultado anterior. Si el cliente muestra dos cargos, utiliza el diagnóstico de cobro duplicado en Clip Total 3 y los mecanismos oficiales de aclaración.
Cómo distinguir intención, operación en proceso y pago confirmado
Un sistema de ventas necesita una regla clara para marcar una orden como pagada. Esta separación evita que el personal entregue mercancía sólo porque su servidor recibió un HTTP 200:
| Etapa | Evidencia disponible | Qué mostrar al negocio |
|---|---|---|
| Solicitud creada | Respuesta del POST e identificador de intención | «Cobro solicitado; pendiente de confirmación» |
| Dispositivo en uso o resultado pendiente | Estado en API y consulta todavía no concluyente | «Verificando el pago; no repetir» |
| Pago aprobado | Resultado final confirmado por API y conciliado con la orden | «Pago aprobado» y referencia verificable |
| Pago rechazado, cancelado o no confirmado | Resultado explícito o incidente pendiente de aclarar | Mensaje que no simule aprobación; derivar a revisión |
Estos mensajes son propuestas de diseño para tu software, no textos obligatorios de Clip. No construyas una automatización que marque «pagado» por la mera creación de la intención. Tampoco asumas que un tiempo de espera en tu backend significa que la tarjeta no fue cargada. Tu lógica debe consultar la API y reconciliar la venta antes de decidir si procede otra operación.
Ejemplo hipotético: el POST respondió 200, pero Total 3 no cambió de pantalla
Imagina que el sistema de una tienda envía el cobro de un pedido identificado internamente como PEDIDO-1042. El servidor recibe un identificador de intención, mientras el cajero no observa ninguna pantalla de pago. En lugar de pulsar «cobrar» de nuevo, el responsable registra esa referencia y consulta el estado de los dispositivos. Si obtiene [], comprueba el número de serie, la cuenta y el aprovisionamiento de PinPad; si obtiene active, consulta el detalle de la intención y revisa la correspondencia con el serial.
Si la primera operación queda sin estado final confiable, el pedido permanece pendiente de aclaración. La decisión de reintentar se toma únicamente cuando el comercio tiene evidencia suficiente de que no generará un segundo cargo. Este ejemplo ilustra un control de riesgo; no representa una prueba ejecutada por ENT Terminal.
Qué información enviar al soporte técnico de Clip
Cuando el registro no aparece, la app PinPad no se instala o el estado no mejora tras verificar los requisitos, abre una consulta en los canales oficiales para desarrolladores indicados en su documentación. Prepara modelo Clip Total 3, serial, identificador del comercio o cuenta autorizado, etapa del flujo donde se detiene, endpoint, código de respuesta y referencia de la intención. Describe si la app está instalada, visible y con sesión iniciada.
No compartas tokens, contraseñas, encabezados completos de autorización, claves privadas, NIP ni datos completos de tarjeta en foros públicos, capturas o correos sin protección. Si aportas registros, elimina datos personales innecesarios. El soporte puede solicitar comprobaciones adicionales por un canal seguro.
La app PinPad y sus requisitos son específicos de una integración para desarrolladores. Para un negocio que sólo quiere aceptar tarjetas sin software externo, quizá baste el funcionamiento autónomo habitual de Total 3; no necesitas implementar una API para utilizar las funciones de cobro que ya incluye.
Fuentes oficiales consultadas y alcance
- Clip Developers: introducción a la API PinPad, requisitos, modelos compatibles y producción.
- Clip Developers: crear una intención de pago, diferencia entre solicitud y operación.
- Clip Developers: estado de los dispositivos, interpretación de disponibilidad.
- Clip Developers: consulta de una intención, verificación de resultado.
- Respuesta del equipo de Clip en foro técnico sobre Total 3, caso específico de despliegue remoto.
Contenido educativo para México, revisado el 7 de noviembre de 2026. Los endpoints, permisos, estados y procedimientos dependen de la documentación y habilitaciones de Clip vigentes. No realizamos cobros de prueba ni tenemos acceso a la cuenta del comercio lector.
¿Todavía estás evaluando Clip Total 3?
Si necesitas una terminal autónoma con inventario, impresora y posibilidad de explorar una integración mediante API, revisa primero si el proveedor habilita el modo PinPad para tu cuenta y tus necesidades. La terminal por sí sola no garantiza que una integración propia esté lista al sacarla de la caja.
Consultar Clip Total 3 y sus condiciones vigentes
Divulgación: el enlace anterior es de referido. ENT Terminal podría recibir una bonificación por una compra elegible; ello no modifica las condiciones ni la configuración técnica que determine Clip.