Antes de la entrega de su matriz de pruebas

📘

Este documento es completo por sí solo

Reúne todo lo que la certificación evalúa, de modo que no necesitará ningún otro material para prepararse. Si dispone de poco tiempo, el último apartado concentra lo que con mayor frecuencia obliga a repetir una prueba o a reabrir un punto, y le sugerimos leerlo antes de comenzar. Cuando NetPay le entregue su matriz de pruebas, todo esto le llegará ya filtrado para su integración, y a partir de ese momento el documento que le corresponderá es Siguientes pasos tras recibir su matriz de pruebas.

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

1. El alcance se ajusta a su integración

No todos los comercios certifican lo mismo. El alcance se define con tres datos: cómo integró, qué APIs adicionales utiliza y con qué marca de terminal trabaja. A partir de ellos se determinan las preguntas que deberá responder y los escenarios que deberá ejecutar.

Identificación de su modalidad

NetPay identifica cada modalidad con un nombre técnico. A continuación se describen en lenguaje natural, para que pueda ubicar la que corresponde a su implementación:

Las APIs adicionales

Puede utilizar más de una. Cada una añade escenarios concretos a su certificación:

La marca de la terminal

Pax, Urovo o Kozen. Conviene conocer el alcance real de cada una:

• Pax es la marca con mayor cobertura: prácticamente todos los escenarios existen para ella.
• Urovo cubre un conjunto más acotado, centrado en venta, promociones, reimpresiones y reversos, e incorpora escenarios propios como la validación de reversos en CoreX.
• Kozen es una integración reciente y todavía no tiene escenarios definidos. Si su terminal es de esta marca, le sugerimos acordar el alcance de las pruebas con el equipo de integraciones antes de la sesión.

⚠️

Esta guía describe el comportamiento de las terminales Pax

Tanto la documentación publicada como los escenarios de prueba se construyeron sobre terminales Pax, que es la marca con mayor cobertura y sobre la que se apoya la mayoría de las integraciones. En Urovo y en Kozen, algunos flujos —de forma señalada el de reversos— pueden comportarse de manera distinta: cambian los mensajes en pantalla, los tiempos o los valores devueltos. Si su terminal es de alguna de estas dos marcas, le sugerimos confirmar por correo con el equipo de integraciones las diferencias que apliquen a su modelo antes de ejecutar las pruebas.

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. El ticket personalizado

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

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"]

5. La información que se registra de su proyecto

Antes de evaluar nada técnico, NetPay levanta el expediente de su proyecto: contactos, datos de la integración y datos de la terminal. No son pruebas, pero es la información que el equipo de integraciones consulta al atender un caso posterior.

6. Puntos que se validan de su sistema

Antes de iniciar las pruebas con la terminal, NetPay le pedirá por escrito cómo resolvió una serie de puntos. No son preguntas de opinión: cada una tiene un resultado esperado con el que se contrasta su respuesta. El listado completo, ya filtrado para su integración, está en el apartado 9.

Dos precisiones aplican a los tres canales por igual y conviene leerlas antes de contestar.

📘

Alcance de los registros solicitados

No se solicitan los registros que la terminal envía a soporte ante una falla. La certificación revisa los registros de su punto de venta, y estos deben acreditar que su sistema recibe la respuesta completa y sin alteraciones: sin filtrar campos, sin descartar aquellos que actualmente no utiliza y sin truncarla al almacenarla. Según su canal, la respuesta se recibe por el webhook (API), por la librería .aar (SDK) o por la .dll (COM); en los tres casos debe registrarse íntegra antes de que su sistema realice cualquier procesamiento sobre ella.

El motivo es operativo: ante un caso de soporte productivo, la primera comparación que se realiza es entre lo que NetPay envió y lo que su sistema registró. Si el registro se encuentra truncado, esa comparación no es posible.

Las páginas que documentan cada uno de estos puntos son las mismas que se listan en el apartado 3, ordenadas por canal. Si al responder alguna de las preguntas necesita revisar la referencia, ese es el índice a consultar.

7. 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.

8. Escenarios que deberá ejecutar

Cada escenario 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.

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

9. Su alcance según su integración

Los apartados anteriores explican qué se valida y por qué. Este le dice cuánto le corresponde a usted. Es el mismo contenido que recibirá dentro de su matriz de pruebas, aquí sin filtrar.

Cada pestaña muestra el alcance de una integración estándar en ese canal. Si además utiliza OAuth, Smart Accounts, cashback, MDB IM30 o check-in y check-out, la variante correspondiente detalla únicamente lo que cambia respecto de esa base.

10. 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.

11. Puntos importantes que pueden retrasar la certificación

Este apartado reúne lo que con más frecuencia obliga a repetir una prueba o a reabrir un punto durante la revisión. Le sugerimos leerlo antes de ejecutar los escenarios, 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 8.

❗

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