Después de recibir su matriz de pruebas

📘

Consideraciones previas a su sesión de certificación

Al contar ya con la matriz de pruebas que NetPay le ha entregado, filtrada para su integración, este documento reúne de forma sintetizada las consideraciones que conviene tener resueltas y presentes antes de la sesión de certificación en la que la completará: cómo se organiza el documento y qué le corresponde llenar en cada hoja, las reglas que su sistema debe cumplir, los pasos de los bloques que deben provocarse en la terminal, el significado de cada estatus y los puntos que con mayor frecuencia obligan a repetir una prueba.

Si dispone de poco tiempo, le sugerimos comenzar por el último apartado.

Forma parte de la Guía de Certificación de Integración NetPay.

1. Cómo está organizada su matriz de pruebas

Su matriz de pruebas es un documento de hojas de cálculo. Cada hoja cubre una parte del proceso, y en todas ellas las celdas que le corresponde llenar están marcadas con borde punteado.

Las columnas de Estatus y de Comentarios de NetPay las completa el equipo de integraciones durante la revisión: no deben modificarse.

⚠️

El trabajo se realiza sobre el documento que NetPay le compartió

Le sugerimos no reconstruirlo, copiarlo a otro archivo ni reordenar sus filas. La numeración de los escenarios y el vínculo entre las hojas Pruebas y Evidencias dependen de esa estructura, y la revisión se realiza sobre ese mismo documento.

📘

Su matriz de pruebas ya trae el alcance aplicado

Las preguntas y los escenarios que contiene son los que corresponden a su tipo de integración, sus APIs adicionales y su marca de terminal. Si su alcance cambia durante el proyecto, avise al equipo de integraciones: la matriz de pruebas debe regenerarse.

2. Material que debe preparar

Le recomendamos reunir los siguientes elementos antes de comenzar. Su ausencia es la causa más frecuente de retraso en una certificación.

La terminal de pruebas

La solicita su asesor comercial o distribuidor de NetPay, no el equipo de integraciones, y debe entregarse en modo de pruebas.

La configuración exacta no es única: depende del modelo, de la marca, de la versión del procesador de pagos y del tipo de integración, y la combinación varía de un caso a otro. Por eso el equipo de integraciones indica en cada solicitud qué versiones corresponden. En términos generales, al recibir la terminal conviene tener identificado y confirmado lo siguiente:

• El modelo y la marca del equipo.
• La versión de Smart PinPad instalada.
• La versión de la aplicación de soporte y del launcher.
• Los servicios de Google instalados, cuando el tipo de integración lo requiera.
• Si la terminal debe entregarse en modo debug, como ocurre en las integraciones por SDK.

❗

La terminal no debe tener instalada la App de Pagos

Es el error de configuración que con más frecuencia impide iniciar una certificación. Si la terminal llega con la App de Pagos instalada, o con versiones distintas de las indicadas para su caso, le sugerimos reportarlo con su asesor comercial o distribuidor sobre el mismo ticket en el que se solicitó, para que el área de almacén de NetPay pueda revisarlo. Una vez recibida la terminal, es recomendable contactar al equipo de integraciones para verificar que la configuración sea la correcta antes de comenzar.

Credenciales de prueba

Las credenciales de acceso a la aplicación Smart PinPad Dev y las de generación del token no se publican en la documentación. Por política de seguridad, el equipo de integraciones las envía por correo únicamente a los prospectos que han seguido el proceso comercial correspondiente. Si aún no las ha recibido, puede solicitarlas por ese mismo medio.

Material complementario

Ambiente: las pruebas se ejecutan en el ambiente de PRUEBAS. Su sistema debe poder alternar entre los ambientes de pruebas y producción mediante configuración (URL base, path y body del token), sin necesidad de recompilar.

⚠️

Sobre el NIP durante las pruebas

Siguiendo la documentación, ningún cobro del ambiente de pruebas es real y no se genera cargo alguno a las tarjetas utilizadas. El NIP es la única excepción: se valida directamente con el banco emisor, por lo que debe ingresarse correctamente. Tres o más intentos incorrectos pueden ocasionar el bloqueo de la tarjeta.

3. La documentación de referencia, por canal

La mayor parte de lo que la certificación evalúa ya se encuentra documentada. Dado que la documentación está organizada por canal, esta guía mantiene la misma separación: le sugerimos consultar únicamente la pestaña correspondiente a su implementación. Una integración por SDK no configura una URL de regreso, y una integración por API no compila una aplicación para la terminal.

Si alguna de sus respuestas no coincide con lo indicado en la página correspondiente, es probable que ese punto se reabra durante la revisión.

📘

Temas cubiertos exclusivamente en esta guía

Algunos temas que la certificación evalúa aún no cuentan con una página propia: el cashback y sus condiciones mínimas, los tiempos de espera, el bloqueo de multi-instancias y el check-in por COM. En estos casos, la presente guía constituye la referencia aplicable, y cualquier detalle adicional puede solicitarse por correo al equipo de integraciones.

4. Reglas transversales que su sistema debe cumplir

Estas reglas se repiten a lo largo del cuestionario y de varios escenarios. Conviene resolverlas desde el principio, ya que cada una de ellas afecta a un bloque completo de la certificación.

Tiempos de espera

Bloqueo de multi-instancias

Su sistema no debe permitir enviar dos ventas al mismo tiempo: tras el primer envío, el control debe quedar bloqueado hasta recibir la respuesta, y la operación no debe generar ventas duplicadas. La misma regla aplica a la cancelación: pulsar el botón varias veces seguidas no debe producir intentos duplicados.

El campo con el que se valida el resultado

responseCode con valor 00 indica transacción aprobada; cualquier otro valor representa un error o una declinación. En SDK también es válido el campo success. El texto impreso en el ticket no es una fuente válida para determinar el resultado.

Cancelación

Debe realizarse el mismo día de la venta y, como referencia, antes de las 20:00 hora de Ciudad de México.

Restricciones de red en sus sucursales

📘

El firewall de sus sucursales puede bloquear las transacciones

Es una causa frecuente de fallas que aparecen solo en algunas sucursales y no en el ambiente de desarrollo. Si su red aplica controles de acceso o filtrado de tráfico, deben habilitarse las URLs, los puertos y las direcciones IP que utiliza la comunicación con NetPay, tanto en pruebas como en producción.

Por tratarse de información sensible, el listado vigente se mantiene en un documento de acceso restringido: matriz de URLs y puertos. Al abrirlo se le pedirá solicitar acceso; la autorización la otorga el equipo de integraciones. Conviene aplicar la configuración antes de la sesión de certificación, ya que una restricción de red no detectada a tiempo detiene la ejecución de los escenarios.

Recuperación de una venta por orderId

Cuando recupere mediante la reimpresión por orderId una venta que no llegó a su sistema, ese valor debe tomarse del ticket físico impreso, nunca de otra fuente.

5. El ticket personalizado

Va antes que el resto por una razón práctica: cuando el ticket personalizado aplica, se certifica antes que las demás pruebas, y si más adelante se modifica, las evidencias ya entregadas deben repetirse. Si mantiene el voucher oficial de NetPay, puede pasar directamente al apartado 6.

Casos en los que aplica

flowchart TD
    A{"¿Aplica el ticket<br/>personalizado?"}
    A -->|"mantiene el voucher<br/>oficial de NetPay"| Z["No se evalúa"]
    A -->|"lo desactiva, o la<br/>terminal no imprime"| B{"¿Cumple la<br/>versión mínima?"}
    B -->|"por debajo"| N["Ticket Personalizado<br/>No Certificado"]
    B -->|"SDK 1.1.9<br/>DLL 1.6.0"| C{"¿Smart PinPad<br/>2.0 o mayor?"}
    C -->|"no"| N
    C -->|"sí"| D{"¿Certificado antes<br/>y sin cambios?"}
    D -->|"sí"| E["Se puede omitir"]
    D -->|"no"| F["Debe certificar<br/>su ticket personalizado"]

Dos condiciones encadenadas: primero la versión correspondiente a su canal y después la de la terminal. El incumplimiento de cualquiera de ellas no deja el punto pendiente, sino que lo registra como «No Certificado».

Los cuatro requisitos aplicables

⚠️

Consecuencia de no cumplir los requisitos

Cuando el ticket personalizado no puede certificarse, NetPay lo registra explícitamente como «Ticket Personalizado 'No Certificado'». Deshabilitar el voucher oficial sin haber certificado el propio implica asumir los riesgos operativos correspondientes, así como las implicaciones frente a la normativa bancaria vigente.

Detalle para quienes deben certificarlo

Si tras el diagrama anterior confirmó que debe certificar su ticket, despliegue lo que sigue. Si mantiene el voucher oficial de NetPay, puede omitirlo por completo.

flowchart TD
    A["Respuesta de la venta"] --> B{"¿hasPin<br/>es true?"}
    B -->|"sí"| C["FIRMADO<br/>ELECTRÓNICAMENTE"]
    B -->|"no"| D{"¿hexSign trae<br/>algún valor?"}
    D -->|"sí"| E["FIRMA<br/>DIGITALIZADA"]
    D -->|"no"| F["AUTORIZADO<br/>SIN FIRMA"]

6. Cómo se evalúa cada punto

Cada escenario de la hoja Pruebas se ejecuta en la terminal y se respalda con la captura del ticket y el JSON de respuesta de esa misma transacción.

Criterio de evaluación de cada escenario

flowchart TD
    A["Consulta el escenario<br/>que le corresponde"] --> B["Ejecuta la prueba<br/>en la terminal"]
    B --> C["Resguarda el ticket<br/>y el JSON"]
    C --> D["Los entrega<br/>como evidencia"]
    D --> E{"NetPay contrasta<br/>con lo esperado"}
    E -->|"cumple"| F["Realizado"]
    E -->|"parcial"| G["A<br/>Mejorar"]
    E -->|"no<br/>existe"| H["No<br/>Implementado"]
    E -->|"faltó<br/>material"| I["No<br/>realizado"]

Los cuatro estatus posibles no representan grados de una misma condición: dos se refieren al alcance de su sistema y dos a la ejecución de la prueba. De ahí la importancia de contar con todo el material antes de iniciar.

Niveles de obligatoriedad

Evidencia que debe entregar

Para cada escenario que así lo requiere, se adjunta:

1. La captura del ticket impreso por la terminal.
2. El JSON de respuesta recibido por su sistema.

Ambos elementos deben corresponder a la misma transacción. La discrepancia entre ellos —el ticket de una prueba acompañado del JSON de otra— es la observación más frecuente de todo el proceso.

7. Bloques que requieren pasos concretos

Dos bloques de su matriz de pruebas no se resuelven leyendo el resultado esperado: es necesario provocar la situación en la terminal. Estos son los pasos.

Reversos, de implementación obligatoria

Un reverso se produce cuando la comunicación se interrumpe a mitad de una transacción. Aplica a los tres canales y su manejo mediante la reimpresión por folio es de implementación obligatoria. Es un flujo poco frecuente, pero conviene dejarlo resuelto durante la certificación: cuando está bien implementado, el propio sistema del comercio resuelve el caso sin necesidad de consultarlo con NetPay. Existen dos tipos, con comportamientos distintos: el automático, que la terminal resuelve por sí sola, y el manual, que necesita una transacción posterior para completarse.

⚠️

Los pasos y los mensajes descritos en este bloque corresponden a terminales Pax. En Urovo y en Kozen el flujo de reversos puede diferir; le sugerimos confirmarlo con el equipo de integraciones si su terminal es de alguna de esas marcas.

flowchart TD
    S["Venta en curso<br/>tarjeta y NIP"]
    S --> P["Procesando<br/>Autorización"]
    P -->|"se<br/>completa"| A["APROBADA"]
    P -->|"se retira<br/>la tarjeta"| DEC["DECLINADA<br/>código 05"]
    P -->|"se apaga<br/>la terminal"| SIN["SIN<br/>RESPUESTA"]
    A --> AC["Reimpresión:<br/>Aprobada · C"]
    DEC --> RC["Reimpresión:<br/>Reversada · RV"]
    RC --> FIN1["Reverso automático<br/>concluido"]
    SIN --> PC["Reimpresión:<br/>Pendiente · PRV"]
    PC --> V2["Venta normal<br/>el mismo día"]
    V2 --> RC2["Reimpresión:<br/>PRV pasa a RV"]
    RC2 --> FIN2["Reverso manual<br/>concluido"]
    classDef ok fill:#e8f5e9,stroke:#43a047,color:#1b5e20
    classDef ko fill:#fff3e0,stroke:#fb8c00,color:#e65100
    classDef nd fill:#ffebee,stroke:#e53935,color:#b71c1c
    class A,AC,FIN1,FIN2,RC,RC2 ok
    class DEC,PC ko
    class SIN nd

Los tres desenlaces de una venta y el valor que devuelve la reimpresión por folio en cada uno. La rama central corresponde al reverso automático y la rama derecha al reverso manual: en esta última, la transacción permanece en «Pendiente por Reversar» hasta que una venta posterior del mismo día detona el reverso. Los pasos exactos para provocar cada rama se detallan a continuación.

Cómo reproducir cada escenario

Los pasos exactos están abajo. Despliéguelos cuando vaya a ejecutar las pruebas.

❗

El voucher personalizado en los escenarios de reverso: son dos impresiones

Si su integración emite su propio voucher, cada uno de estos escenarios produce dos tickets distintos, y ambos se entregan como evidencia.

1 · El de la venta declinada. Es la variante de declinación de su voucher, e incluye el responseCode original —05 o el que entregue la terminal para ese error— y el mensaje original del error en una línea.

2 · El de la reimpresión por folio. Es un ticket aparte, con la leyenda -----DUPLICADO----- cuando isRePrint devuelve true, y con el mensaje que entrega la reimpresión: «Transacción Reversada» o «Transacción Pendiente por Reversar».

Sus campos son los de la tabla Revisión de ticket de Declinación de la hoja TICKET-PERSONALIZADO, que es una de las cuatro que se certifican.

Los escenarios que se ejecutan y se evalúan

Los valores que devuelve la reimpresión por folio

Si almacena estos escenarios en su base de datos, los estatus de esas ventas deben actualizarse. El campo que debe consultar es reprintModule dentro del objeto JSON de respuesta, no responseCode:

En terminales Urovo con CoreX, la reimpresión posterior al reverso devuelve además responseCode con valor R. En el escenario de reverso automático sobre CoreX en integraciones SDK, la respuesta llega con message «Transacción Reversada», reprintModule con valor RV y responseCode con valor R40.

❗

La terminal es la fuente de verdad

Ante cualquier discrepancia de estatus entre NetPay Manager y la terminal, debe prevalecer el resultado de la reimpresión por folio en la terminal. Ninguna otra consulta es una fuente válida para determinar el estatus de un reverso.

Check-in y check-out, si su integración lo incluye

Aplica únicamente a las modalidades checkinAPI-checkoutAPI, checkinSDK-checkoutAPI y checkinCOM-checkoutAPI. Si la suya no es una de ellas, puede omitir este apartado.

flowchart TD
    A["Check-in desde su canal<br/>checkIn: true"] --> B["La terminal procesa<br/>la preautorización"]
    B --> C["Imprime el ticket oficial<br/>de NetPay"]
    C --> D["Respuesta con transType PRE<br/>y transactionId"]
    D --> E["Check-out por la API CheckIO<br/>con storeId, transactionId<br/>y totalAmount"]
    E --> F["La API confirma el cierre<br/>sin imprimir ticket"]
    F --> G["Reimpresión por folio<br/>para obtener el comprobante"]
    classDef term fill:#e8f0fe,stroke:#4a6fa5,color:#12233d
    classDef api fill:#fff4e5,stroke:#c98a2e,color:#4a3208
    class A,B,C,D,G term
    class E,F api

8. Interpretación de los estatus

Cada pregunta y cada escenario recibe un estatus durante la revisión. Esta tabla le será útil sobre todo cuando NetPay le devuelva sus resultados.

9. Puntos importantes que pueden retrasar la certificación

Estos son los puntos que con más frecuencia obligan a repetir una prueba o a reabrir un punto durante la revisión. Le sugerimos leerlos antes de empezar a llenar su matriz de pruebas, no después.

Lo que con más frecuencia genera retrasos

1. Definir tarde el alcance. Cambiar el tipo de integración con el trabajo ya avanzado modifica las preguntas y los escenarios que aplican, y obliga a revisar de nuevo lo ya respondido.
2. Responder el cuestionario sin verificar. Cada respuesta se contrasta con el comportamiento observado durante las pruebas, y cualquier incongruencia reabre el punto.
3. Tiempos de espera insuficientes. Un temporizador de 60 segundos en el frontend compromete buena parte del bloque de esperas.
4. Folio no único. Si el folio se repite entre sucursales o en operaciones declinadas, la recuperación por reimpresión deja de ser posible y varios escenarios quedan sin resolver.
5. Evaluar el resultado con un campo distinto al indicado. El campo aplicable es responseCode (00), o success en SDK; no el texto impreso en el ticket.
6. Utilizar Print-Ticket para consultar el estatus de reversos. La documentación indica que no es fiable para ese fin; debe emplearse la reimpresión por folio.
7. Enviar el orderId corto en devoluciones. La API de devoluciones requiere el orderId largo que devuelve Print-Ticket.
8. Evidencias cruzadas. El ticket de una prueba acompañado del JSON de otra.
9. Iniciar la sesión sin el material requerido. Sin tarjeta contactless, sin un BIN habilitado para cashback o sin la versión mínima de Smart PinPad, la prueba se registra como No realizado por falta de insumos.
10. Desactivar el voucher oficial sin certificar el propio. Conduce directamente al estatus Ticket Personalizado 'No Certificado'.

Precisiones sobre funcionalidades concretas

Los dos primeros aplican a cualquier integración; los siguientes solo si su sistema ofrece esa funcionalidad, por lo que se presentan plegados.

Aplica a toda integración

❗

El manejo de reversos es de implementación obligatoria

No es opcional ni depende de su tipo de integración: aplica a API, SDK y COM por igual, y se resuelve mediante la reimpresión por folio. Es un flujo poco frecuente y, precisamente por ello, suele quedar para el final y llegar sin implementar a la sesión de certificación. Los dos tipos de reverso, los pasos para provocar cada uno y los valores que devuelve la reimpresión están en el apartado 7.

❗

Una venta de su sistema puede corresponder a varias transacciones en la terminal

Ocurre en las ventas parciales y en cualquier cobro que se liquide con más de una tarjeta o en más de un intento. Para su sistema es una sola venta, con un importe único y un solo registro en su base de datos; para la terminal son transacciones independientes, y cada una tiene su propia autorización y su propio resultado.

Por esa razón, cada transacción enviada a la terminal debe llevar un folio distinto. Si dos cobros comparten el mismo folio, la consulta por folio devolverá únicamente uno de ellos y el otro quedará sin trazabilidad. Ese es precisamente el punto que se valida.

Aplica solo si su integración lo incluye