Getnet DocsGetnet Docs

Solución de problemas

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Esta guía te ayuda a diagnosticar fallas durante una integración con el SDK White Label y a decidir qué hacer con cada una. Cubre las fallas que manejas en tu propia aplicación. Incluye problemas de warm-up, pagos rechazados, errores de servicio, fallas de lectura de tarjeta, tiempos de espera agotados y reembolsos fallidos.

Para el catálogo completo de códigos de resultado y mensajes, consulta Referencia de códigos de error.

Lee primero el código de resultado

Cada falla trae un código de resultado con un prefijo que indica la clase de falla. Lee el prefijo antes que nada.

PrefijoClaseDe dónde viene
00AprobadaLa transacción tuvo éxito.
1-Error de terminalTerminal local, lectura de tarjeta u operador (por ejemplo, 1-02 cancelada, 1-21 error genérico de terminal).
33-Error de hostServicio de pagos (SEP): un error HTTP o un rechazo del emisor.

El código llega a tu aplicación en TransactionResult.result, con un resultMessage legible. Trata 00 como aprobación y cualquier otro valor como no aprobación.

Los errores de host están migrando del prefijo antiguo 4-xx a 33-xx: los dígitos se mantienen (4-503 pasa a ser 33-503). Los terminales que aún no se actualizaron pueden seguir devolviendo 4-xxx. Trata 4-xxx y 33-xxx como equivalentes.

Identifica la pantalla de error

En los flujos con tarjeta, el SDK muestra una de dos pantallas de error antes de devolver el control a tu aplicación. Pix tiene su propia pantalla de error.

PantallaCuándo apareceQué debe hacer el operador
Pago rechazadoEl terminal leyó la tarjeta correctamente, pero el emisor rechazó el pago (33-<reason>).El rechazo viene del banco del titular, no del terminal. Pide otra tarjeta o indica al cliente que contacte a su banco.
Pago interrumpidoEl servicio de pagos falló o no estaba disponible: un error de host o un tiempo de espera agotado (33-5xx).Consulta el estado de la transacción antes de reintentar, para no cobrar dos veces. Si sigue ocurriendo en varios terminales, trátalo como un incidente de plataforma.

Clasifica la falla

Cada no aprobación entra en una de estas categorías. La categoría te indica si la manejas en tu aplicación, si pides una acción al operador o si contactas a Getnet.

CategoríaQué significaQué haces
Titular / tarjetaEl emisor o la tarjeta rechazó la operación.Pide otra tarjeta o indica al cliente que contacte a su banco. No es una falla del terminal ni de la aplicación.
Transitoria — reintentaUna condición temporal.Espera unos segundos y reintenta. Después de un tiempo de espera agotado, consulta primero la transacción.
Duplicada / en cursoLa transacción puede estar ya completa o cancelada.Revisa el recibo impreso o consulta el pago antes de reintentar. No reintentes a ciegas.
Referencia no encontradaEl paymentId o la referencia no coincide con ninguna transacción.Confirma el paymentId y el entorno usado en el reembolso o la consulta.
Configuración de comercio / productoEl comercio, el producto, la marca de tarjeta o el terminal no está habilitado para esta operación.Reúne el código del terminal y el ID del comercio, y contacta a Getnet.
AutenticaciónEl terminal no pudo autenticarse con el gateway.Confirma el entorno y que configuraste credenciales válidas.
Integración / solicitudLa validación rechazó la solicitud, o la solicitud estaba mal formada.Es un problema de software: captura el payload del resultado y corrige la integración.
Plataforma / sistemaUna falla del lado del servidor.Reintenta una vez después de una breve espera. Si persiste o afecta a varios terminales, trátalo como un incidente de plataforma.

Escenarios comunes

Cada escenario indica el síntoma, su causa probable y la solución.

El warm-up falla y el SDK nunca queda listo

El SDK informa Failure(cause) a través de setOnWarmUpStatus, o una operación nunca inicia.

Causa. El warm-up carga la configuración del terminal y se autentica con el servicio de pagos. Falla si no hay conexión de red, si las credenciales son incorrectas o si el terminal no está registrado.

Solución

  1. Revisa el Wi-Fi o los datos móviles del terminal.
  2. Inspecciona el código de error del warm-up. De -1 a -5 son condiciones de red: reintenta. 401 significa que el clientId / clientSecret o el entorno son incorrectos. 404 significa que el terminal no está registrado para esta configuración.
  3. Para recuperarte, llama a ApoloSdk.shutdown() y luego configura y ejecuta build() de nuevo.
  4. Si un 401, 404 o 422 persiste, confirma las credenciales, el terminalCode y el entorno con Getnet.

Consulta los códigos de warm-up en Referencia de códigos de error.

Un pago es rechazado

El terminal lee la tarjeta con normalidad, pero el resultado es 33-<reason> y aparece la pantalla “Pago rechazado”.

Causa. El emisor rechazó la autorización: por ejemplo, fondos insuficientes, tarjeta bloqueada o tarjeta vencida. Esto depende del lado del titular de la tarjeta, no de una falla del terminal.

Solución

  1. Pide al cliente otra tarjeta, o indícale que contacte a su banco.
  2. Escala el caso solo si una tarjeta que el cliente considera válida falla en varios terminales.

“Pago interrumpido” — error de servicio

Aparece la pantalla “Pago interrumpido” con un código 33-5xx (por ejemplo, 33-500, 33-503, 33-504).

Causa. El servicio de pagos falló o no estuvo disponible de forma temporal: una condición del lado del servidor o un tiempo de espera agotado.

Solución

  1. No reintentes de inmediato.
  2. Consulta la transacción por paymentId para confirmar si se procesó.
  3. Si no se procesó, reintenta una vez después de una breve espera.
  4. Si persiste o afecta a varios terminales, trátalo como un incidente de plataforma y contacta a Getnet.

La tarjeta no se lee

El terminal repite “insertar, acercar o deslizar”, o el contactless falla.

Causa. Falló una lectura contactless o por chip. Suele ser un fallback normal, no un error.

Solución

  1. Pide al cliente que inserte el chip. Si el chip falla, pídele que deslice la banda magnética.
  2. Si el terminal detecta varias tarjetas a la vez, pide al cliente que presente una sola, lejos de otras tarjetas o de la billetera.
  3. Si una tarjeta específica falla con todos los métodos, pide otra tarjeta.

Tiempo de espera agotado — no sabes si se cobró al cliente

El resultado es un tiempo de espera agotado (33-504) o la operación termina sin un resultado claro.

Causa. La respuesta no llegó dentro de la ventana de tiempo de espera, así que el resultado es desconocido: el cobro puede haberse completado o no.

Solución

  1. No inicies todavía una nueva venta por el mismo monto.
  2. Consulta la transacción por paymentId para confirmar si fue autorizada.
  3. Inicia una nueva venta solo después de confirmar que la primera no se procesó.

Un reembolso o una cancelación falla con “not found”

El reembolso devuelve un 33-404 con un mensaje “not found”.

Causa. El paymentId o el entorno usado para el reembolso no coincide con la transacción original. Una referencia incorrecta es la causa más común.

Solución

  1. Confirma el paymentId de la transacción original.
  2. Confirma que estás ejecutando en el mismo entorno donde hiciste la venta.
  3. Reintenta el reembolso con la referencia corregida.

La transacción se reporta como duplicada o ya existente

El resultado indica que la transacción ya está en curso, ya se realizó o ya se canceló.

Causa. La operación ya se completó, o todavía está en proceso.

Solución

  1. Revisa el recibo impreso o consulta el pago antes de actuar.
  2. No repitas la operación hasta confirmar su estado real.

Antes de contactar a Getnet

Algunas fallas requieren soporte de Getnet: configuración, autenticación, un 5xx persistente, un terminal bloqueado o un error interno de EMV. Reúne esta información antes de contactarlos, para que soporte pueda localizar la transacción y reproducir el problema.

ReúneDetalle
Código de resultadoEl TransactionResult.result completo (por ejemplo, 33-503, 1-21) y el mensaje en pantalla.
error_code / reason_codeEn los errores de host, el error_code y el reason_code del payload de la respuesta (details[]).
paymentIdEl paymentId (y el orderId, si existe) de la transacción afectada.
TerminalEl número de serie del terminal y el terminalCode configurado.
EntornoPreproducción, homologación o producción: qué build ejecuta el dispositivo.
Fecha y horaLa fecha, la hora y la zona horaria del evento.
AlcanceUna tarjeta o terminal frente a varias: un caso aislado o uno generalizado.
Pasos para reproducirMonto, medio de pago, marca de tarjeta y qué hizo el operador.

Siguientes pasos