Java Wrapper

El Java Wrapper permite que un punto de venta desarrollado en Java se comunique con la terminal NetPay (Smart PinPad) para procesar ventas, cancelaciones, reimpresiones y otras operaciones.

Los ejemplos de esta guía utilizan Swing con Java 8 y Gradle 5.1 para mayor compatibilidad.

1. Implementación de la librería

Al generar la aplicación que controlará el punto de venta, se debe agregar el archivo .jar que hace posible la conectividad entre la terminal y el punto de venta. En esta guía se implementa en una aplicación Gradle, ya que el demo adjunto está desarrollado con esta herramienta:

lib/
└── NetPayWrapperConnector-1.0.jar

Inicialización del wrapper

Al inicializar la aplicación, se crea la instancia del conector que se utilizará en todas las operaciones:

// Inicializamos el wrapper
NetPayWrapperConnector netPayWrapperConnector = new NetPayWrapperConnector();
📘

No es necesario asignar un puerto COM

El método setPortCOM() está deprecado y ya no se utiliza. Basta con crear la instancia de NetPayWrapperConnector para comenzar a enviar operaciones a la terminal.

Consideraciones antes de enviar una venta

⚠️

Ingresa el NIP correctamente

Aunque se trate de un ambiente de pruebas, el único valor que el banco valida es el NIP, por lo que si se ingresa de forma incorrecta la tarjeta puede ser bloqueada directamente por el banco.

También es posible utilizar tarjetas vencidas sin ningún problema, siempre y cuando se conozca el NIP con el que funcionaban.

Objetos y métodos disponibles

Una vez instanciado el objeto, se puede acceder a los siguientes objetos y métodos:

SaleDTO: objeto que contiene los atributos para el envío de la venta.

AtributoTipo de datoDescripción
amountDoubleMonto a cobrar.
msiintNúmero de meses sin intereses al momento de procesar la transacción. Por default se envía el valor 0 (sin meses). Valores aceptados: 3, 6, 9, 12, 18.
folioStringFolio personalizado a utilizar en el ticket.
tipdoubleMonto designado a propina.
bankOnlyintIndica si la transacción solo se permite con BINes bancarios.

Métodos:

MétodoDescripción
setDisablePrintAnimationDeshabilita la animación del ticket.
sendSaleProcesa una venta.
sendCancelProcesa la cancelación de una venta previamente realizada (se debe ingresar un orderId existente).
sendPrintEnvía la petición para generar una copia del ticket en la PinPad (se debe ingresar un orderId o folio existente).
testConnectionVerifica la conectividad con la PinPad.
versionDevuelve la versión implementada de la librería.

2. Venta

Se utiliza un ActionListener para ejecutar el proceso en cuanto se presiona el botón saleButton, y un SwingWorker para ejecutar la tarea en segundo plano:

saleButton.addActionListener(new ActionListener() {
    @Override
    public void actionPerformed(ActionEvent e) {
        enableDisableInputs(false);
        logArea.setText("");

        SwingWorker<String, Void> worker = new SwingWorker<String, Void>() {
            @Override
            protected String doInBackground() throws Exception {
                // Enviamos el proceso en segundo plano
                return sendSale();
            }

            @Override
            protected void done() {
                try {
                    // Obtenemos la respuesta al terminar el proceso y la convertimos
                    // en objeto para su mejor manejo (se recibe como JSON)
                    String response = get();
                    TransactionResponseDTO responseDTO =
                        objectMapper.readValue(response, TransactionResponseDTO.class);
                    logArea.setText(response);
                    if (responseDTO != null && responseDTO.getData() != null
                            && responseDTO.getData().getOrderId() != null
                            && !responseDTO.getData().getOrderId().isEmpty()) {
                        // Lo añadimos a la base de datos local con los orderId retornados
                        dbHelper.saveOrderId(responseDTO.getData().getOrderId());
                        refreshOrderIdList();
                    }
                } catch (Exception ex) {
                    logArea.setText("Error: " + ex.getMessage());
                } finally {
                    enableDisableInputs(true);
                }
            }
        };

        worker.execute();
    }
});
private String sendSale() throws Exception {
    SaleDTO sale = new SaleDTO();
    // Validamos que el monto ingresado sea válido
    if (!Util.validAmount(amountValue.getText())) {
        JOptionPane.showMessageDialog(null, "Ingresa un monto valido", "Error", JOptionPane.ERROR_MESSAGE);
        return null;
    }
    sale.setAmount(Double.parseDouble(amountValue.getText()));

    // Validamos y obtenemos el monto de la propina (no obligatorio)
    if (!tipValue.getText().isEmpty()) {
        if (!Util.validAmount(tipValue.getText())) {
            JOptionPane.showMessageDialog(null, "Ingresa un monto de propina valido", "Error", JOptionPane.ERROR_MESSAGE);
            return null;
        }
        sale.setTip(Double.parseDouble(tipValue.getText()));
    }

    // Obtenemos el folio si es ingresado (no obligatorio)
    if (!folioValue.getText().isEmpty()) {
        sale.setFolio(folioValue.getText());
    }

    // Obtenemos la opción de MSI seleccionada en el combo box (no obligatorio)
    Msi msiSelected = Msi.fromControlName((String) msiValue.getSelectedItem());
    if (!msiSelected.equals(Msi.NO_MSI)) {
        sale.setMsi(msiSelected.getFileId());
    }

    // Enviamos la transacción a la PinPad (objeto, timeOut, intervalCheck)
    String response = netPayWrapperConnector.sendSale(sale, 60, 1);

    clearInputs();

    return response;
}

Al llamar al método sendSale se envían los siguientes parámetros:

CampoTipoDescripción
saleSaleDTOObjeto de la venta a procesar.
timeOutintTiempo máximo de espera en segundos antes de que la operación expire (default 180 s).
intervalCheckintIntervalo en milisegundos en el que se revisa la recepción de la respuesta (default 500 ms).
⚠️

Propinas mayores al 25%

Si se requiere el uso de propina y el monto debe ser mayor al 25%, el comercio puede comunicarse con su comercial asignado para que se coordine con el equipo de operaciones y el límite se aumente al porcentaje necesario. Este aumento se realiza en producción, después de terminar la integración y de completar la certificación exitosamente.

3. Cancelación

Se utiliza un ActionListener para ejecutar el proceso en cuanto se presiona el botón cancelButton, y un SwingWorker para ejecutar la tarea en segundo plano:

cancelButton.addActionListener(new ActionListener() {
    @Override
    public void actionPerformed(ActionEvent e) {
        enableDisableInputs(false);
        logArea.setText("");

        SwingWorker<String, Void> worker = new SwingWorker<String, Void>() {
            @Override
            protected String doInBackground() throws Exception {
                // Enviamos el proceso en segundo plano
                return sendCancel();
            }

            @Override
            protected void done() {
                try {
                    // Obtenemos la respuesta al terminar el proceso
                    logArea.setText(get());
                } catch (Exception ex) {
                    logArea.setText("Error: " + ex.getMessage());
                } finally {
                    enableDisableInputs(true);
                }
            }
        };

        worker.execute();
    }
});
private String sendCancel() throws Exception {
    // Validamos y obtenemos el orderId seleccionado en la lista donde lo almacenamos
    if (orderIdValue.getText().isEmpty()) {
        JOptionPane.showMessageDialog(null, "Ingresa un order id", "Error", JOptionPane.ERROR_MESSAGE);
        return null;
    }

    // Enviamos la cancelación a la PinPad (orderId, timeOut, intervalCheck)
    String response = netPayWrapperConnector.sendCancel(orderIdValue.getText(), 180, 100);
    clearInputs();
    return response;
}

Al llamar al método sendCancel se envían los siguientes parámetros:

CampoTipoDescripción
orderIdStringIdentificador de la venta.
timeOutintTiempo máximo de espera en segundos antes de que la operación expire (default 180 s).
intervalCheckintIntervalo en milisegundos en el que se revisa la recepción de la respuesta (default 500 ms).

4. Reimpresión

Se utiliza un ActionListener para ejecutar el proceso en cuanto se presiona el botón rePrintButton:

rePrintButton.addActionListener(new ActionListener() {
    @Override
    public void actionPerformed(ActionEvent e) {
        enableDisableInputs(false);
        logArea.setText("");

        SwingWorker<String, Void> worker = new SwingWorker<String, Void>() {
            @Override
            protected String doInBackground() throws Exception {
                // Enviamos el proceso en segundo plano
                return sendReprint();
            }

            @Override
            protected void done() {
                try {
                    // Obtenemos la respuesta al terminar el proceso
                    logArea.setText(get());
                } catch (Exception ex) {
                    logArea.setText("Error: " + ex.getMessage());
                } finally {
                    enableDisableInputs(true);
                }
            }
        };

        worker.execute();
    }
});
private String sendReprint() throws Exception {
    if (orderIdValue.getText().isEmpty() && folioValue.getText().isEmpty()) {
        JOptionPane.showMessageDialog(null, "Ingresa un order id o folio", "Error", JOptionPane.ERROR_MESSAGE);
        return null;
    }
    // Enviamos la reimpresión a la PinPad (orderId, folioId, timeOut, intervalCheck)
    String response = netPayWrapperConnector.sendPrint(orderIdValue.getText(), folioValue.getText(), 180, 1000);
    clearInputs();
    return response;
}

Al llamar al método sendPrint se envían los siguientes parámetros:

CampoTipoDescripción
orderIdStringIdentificador de la venta.
folioIdStringFolio de la venta.
timeOutintTiempo máximo de espera en segundos antes de que la operación expire (default 180 s).
intervalCheckintIntervalo en milisegundos en el que se revisa la recepción de la respuesta (default 500 ms).

5. Versión

Se utiliza un ActionListener para ejecutar el proceso en cuanto se presiona el botón versionButton:

versionButton.addActionListener(new ActionListener() {
    @Override
    public void actionPerformed(ActionEvent e) {
        try {
            // Ejecutamos el método para obtener la versión de la librería
            getVersion();
        } catch (Exception ex) {
            throw new RuntimeException(ex);
        }
    }
});
private void getVersion() throws Exception {
    // Obtenemos y mostramos la versión de la librería ejecutada
    JOptionPane.showMessageDialog(null, "Version: " + netPayWrapperConnector.version(), "Info", JOptionPane.INFORMATION_MESSAGE);
}

6. Deshabilitar animación del ticket

Se puede deshabilitar la animación del ticket como en el siguiente ejemplo, utilizando un ActionListener para asignar el valor deseado:

// Checkbox para mostrar o no la animación del ticket
printAnimCheckBox.addActionListener(new ActionListener() {
    @Override
    public void actionPerformed(ActionEvent e) {
        try {
            netPayWrapperConnector.setDisablePrintAnimation(printAnimCheckBox.isSelected());
        } catch (Exception ex) {
            throw new RuntimeException(ex);
        }
    }
});

7. Solo banco

En caso de que la integración lo permita y se tenga activa esta operativa, es posible validar que una transacción solo sea válida con BINes bancarios. Antes de enviar la solicitud, se envía el parámetro bankOnly con valor 1, que indica que esta funcionalidad está activa:

private String sendSale() throws Exception {
    SaleDTO sale = new SaleDTO();
    if (!Util.validAmount(amountValue.getText())) {
        JOptionPane.showMessageDialog(null, "Ingresa un monto valido", "Error", JOptionPane.ERROR_MESSAGE);
        return null;
    }
    sale.setAmount(Double.parseDouble(amountValue.getText()));
    if (!tipValue.getText().isEmpty()) {
        if (!Util.validAmount(tipValue.getText())) {
            JOptionPane.showMessageDialog(null, "Ingresa un monto de propina valido", "Error", JOptionPane.ERROR_MESSAGE);
            return null;
        }
        sale.setTip(Double.parseDouble(tipValue.getText()));
    }
    if (!folioValue.getText().isEmpty()) {
        sale.setFolio(folioValue.getText());
    }
    Msi msiSelected = Msi.fromControlName((String) msiValue.getSelectedItem());
    if (!msiSelected.equals(Msi.NO_MSI)) {
        sale.setMsi(msiSelected.getFileId());
    }
    sale.setBankOnly(bankOnlyCheckBox.isSelected() ? 1 : 0); // Activa la validación de solo banco

    String response = netPayWrapperConnector.sendSale(sale, 60, 1);

    clearInputs();

    return response;
}

8. Verificar conexión

Se puede comprobar la conexión con la PinPad usando la función del siguiente ejemplo:

private void testConnection() {
    // Método para verificar la conexión
    boolean result = netPayWrapperConnector.testConnection(180, 500);
    if (result) {
        JOptionPane.showMessageDialog(null, "Conectividad con la TPV exitosa.", "Info", JOptionPane.INFORMATION_MESSAGE);
    } else {
        JOptionPane.showMessageDialog(null, "Sin conectividad con la TPV.", "Info", JOptionPane.WARNING_MESSAGE);
    }
    enableDisableInputs(result);
}

Al llamar al método testConnection se envían los siguientes parámetros:

CampoTipoDescripción
timeOutintTiempo máximo de espera en segundos antes de que la operación expire (default 180 s).
intervalCheckintIntervalo en milisegundos en el que se revisa la recepción de la respuesta (default 500 ms).

9. Modelo de datos de respuesta

CampoDescripciónTipo de dato
affiliationNúmero de afiliación del comercio.VARCHAR2(50 BYTE)
applicationLabelInformación sobre la lectura de la tarjeta.VARCHAR2(100 BYTE)
arqcInformación sobre la lectura de la tarjeta.VARCHAR2(250 BYTE)
aidInformación sobre la lectura de la tarjeta.VARCHAR2(50 BYTE)
amountMonto total de la transacción, incluyendo propina.VARCHAR(250 BYTE)
authCodeValor generado por la autoridad de autorización para una transacción aprobada.VARCHAR2(7 BYTE)
bankNameNombre de la institución financiera emisora de la tarjeta.VARCHAR2(250 BYTE)
cardExpDateFecha de expiración de la tarjeta en formato MM/YY.VARCHAR2(5 BYTE)
cardTypeIdentificador de tipo de tarjeta: débito (D), crédito (C).VARCHAR2(20 BYTE)
cardTypeNameNombre de la marca de la tarjeta: Visa, Mastercard, etc.VARCHAR2(250 BYTE)
cityNameCiudad con la que se dio de alta el comercio.VARCHAR2(150 BYTE)
responseCodeCódigo de respuesta en función del estatus de la transacción. El valor 00 representa una transacción exitosa; cualquier otro valor puede tomarse como un problema con la transacción.VARCHAR2(2 BYTE)
folioNumberNúmero identificador de transacción que puede ser enviado en la solicitud de venta.VARCHAR2(250 BYTE)
hasPinIndica si la transacción fue aprobada mediante NIP.BOOLEAN(FALSE, TRUE)
hexSignFirma autógrafa en caso de que la tarjeta no cuente con NIP.VARCHAR2(4000 BYTE)
isQpsIndica el monto cobrado por Quick Payment Service.NUMBER(15,2)
messageMensaje que indica el estatus de la transacción. Puede indicar si fue aceptada o declinada y el motivo.VARCHAR2(200 BYTE)
moduleChargeIdentificador interno.VARCHAR2(20 BYTE)
moduleLoteIdentificador interno.VARCHAR(9)
customerNameNombre del tarjetahabiente.VARCHAR2(100 BYTE)
terminalIdNúmero de serie de la terminal.VARCHAR2(20 BYTE)
orderIdIdentificador de número de transacción. Puede utilizarse posteriormente en reimpresión y cancelación.VARCHAR2(36 BYTE)
preAuthPreautorización.VARCHAR(9)
preStatusPreautorización.NUMBER(15,2)
promotionNúmero de meses sin intereses en que se parcializó la transacción.VARCHAR2(20 BYTE)
rePrintDateVersión de la aplicación.VARCHAR2(100 BYTE)
rePrintMarkIdentificador interno.VARCHAR2(100 BYTE)
reprintModuleIdentificador interno.VARCHAR2(1 BYTE)
cardNumberÚltimos 4 dígitos de la tarjeta leída.VARCHAR2(50 BYTE)
storeNameNombre del comercio dado de alta.VARCHAR2(60 BYTE)
streetNameDirección del comercio dado de alta.VARCHAR2(150 BYTE)
storeIdID del comercio.VARCHAR(50)
ticketDateFecha y hora de la transacción.VARCHAR2(100 BYTE)
tipAmountMonto de propina, en caso de ser enviado.VARCHAR()
tipLessAmountMonto sin propina.VARCHAR()
transDateFecha, hora y zona horaria (CDT o CST) de la transacción. Ejemplo: 2022-06-13 16:24:24.CDT. Nomenclatura: AAAA-MM-DD HH:MM:SS.ZONA HORARIA.DATETIME
transTypeTipo de operación realizada: venta (A), cancelación (V).VARCHAR2(5 BYTE)
transactionCertificateInformación sobre la lectura de la tarjeta.VARCHAR2(50 BYTE)
traceabilityObjeto para envío de información adicional.OBJECT

Historial de versiones

VersiónFechaAutor(es)Notas de revisión
1.005/05/2025Edson LugoVersión inicial.
1.122/05/2025Edson LugoSe implementa el método para verificación de conexión.
1.226/05/2025Edson LugoSe documenta el uso del parámetro bankOnly.
1.320/06/2025Edson LugoSe cambia el intervalCheck default de 100 a 500 ms. Se modifica el método testConnection con una mejora en la comprobación y se agregan los parámetros timeOut e intervalCheck. Fix de timeouts entre el wrapper y la terminal.
❗️

Todo cambio que afecte la integración o la implementación de nuevas funcionalidades de NetPay debe certificarse con el equipo de integraciones, con el fin de validar su correcta implementación y reducir al mínimo las incidencias en producción.


Did this page help you?