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.jarInicializació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 COMEl método
setPortCOM()está deprecado y ya no se utiliza. Basta con crear la instancia deNetPayWrapperConnectorpara comenzar a enviar operaciones a la terminal.
Consideraciones antes de enviar una venta
Ingresa el NIP correctamenteAunque 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.
| Atributo | Tipo de dato | Descripción |
|---|---|---|
| amount | Double | Monto a cobrar. |
| msi | int | Nú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. |
| folio | String | Folio personalizado a utilizar en el ticket. |
| tip | double | Monto designado a propina. |
| bankOnly | int | Indica si la transacción solo se permite con BINes bancarios. |
Métodos:
| Método | Descripción |
|---|---|
| setDisablePrintAnimation | Deshabilita la animación del ticket. |
| sendSale | Procesa una venta. |
| sendCancel | Procesa la cancelación de una venta previamente realizada (se debe ingresar un orderId existente). |
| sendPrint | Envía la petición para generar una copia del ticket en la PinPad (se debe ingresar un orderId o folio existente). |
| testConnection | Verifica la conectividad con la PinPad. |
| version | Devuelve 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:
| Campo | Tipo | Descripción |
|---|---|---|
| sale | SaleDTO | Objeto de la venta a procesar. |
| timeOut | int | Tiempo máximo de espera en segundos antes de que la operación expire (default 180 s). |
| intervalCheck | int | Intervalo 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:
| Campo | Tipo | Descripción |
|---|---|---|
| orderId | String | Identificador de la venta. |
| timeOut | int | Tiempo máximo de espera en segundos antes de que la operación expire (default 180 s). |
| intervalCheck | int | Intervalo 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:
| Campo | Tipo | Descripción |
|---|---|---|
| orderId | String | Identificador de la venta. |
| folioId | String | Folio de la venta. |
| timeOut | int | Tiempo máximo de espera en segundos antes de que la operación expire (default 180 s). |
| intervalCheck | int | Intervalo 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:
| Campo | Tipo | Descripción |
|---|---|---|
| timeOut | int | Tiempo máximo de espera en segundos antes de que la operación expire (default 180 s). |
| intervalCheck | int | Intervalo en milisegundos en el que se revisa la recepción de la respuesta (default 500 ms). |
9. Modelo de datos de respuesta
| Campo | Descripción | Tipo de dato |
|---|---|---|
| affiliation | Número de afiliación del comercio. | VARCHAR2(50 BYTE) |
| applicationLabel | Información sobre la lectura de la tarjeta. | VARCHAR2(100 BYTE) |
| arqc | Información sobre la lectura de la tarjeta. | VARCHAR2(250 BYTE) |
| aid | Información sobre la lectura de la tarjeta. | VARCHAR2(50 BYTE) |
| amount | Monto total de la transacción, incluyendo propina. | VARCHAR(250 BYTE) |
| authCode | Valor generado por la autoridad de autorización para una transacción aprobada. | VARCHAR2(7 BYTE) |
| bankName | Nombre de la institución financiera emisora de la tarjeta. | VARCHAR2(250 BYTE) |
| cardExpDate | Fecha de expiración de la tarjeta en formato MM/YY. | VARCHAR2(5 BYTE) |
| cardType | Identificador de tipo de tarjeta: débito (D), crédito (C). | VARCHAR2(20 BYTE) |
| cardTypeName | Nombre de la marca de la tarjeta: Visa, Mastercard, etc. | VARCHAR2(250 BYTE) |
| cityName | Ciudad con la que se dio de alta el comercio. | VARCHAR2(150 BYTE) |
| responseCode | Có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) |
| folioNumber | Número identificador de transacción que puede ser enviado en la solicitud de venta. | VARCHAR2(250 BYTE) |
| hasPin | Indica si la transacción fue aprobada mediante NIP. | BOOLEAN(FALSE, TRUE) |
| hexSign | Firma autógrafa en caso de que la tarjeta no cuente con NIP. | VARCHAR2(4000 BYTE) |
| isQps | Indica el monto cobrado por Quick Payment Service. | NUMBER(15,2) |
| message | Mensaje que indica el estatus de la transacción. Puede indicar si fue aceptada o declinada y el motivo. | VARCHAR2(200 BYTE) |
| moduleCharge | Identificador interno. | VARCHAR2(20 BYTE) |
| moduleLote | Identificador interno. | VARCHAR(9) |
| customerName | Nombre del tarjetahabiente. | VARCHAR2(100 BYTE) |
| terminalId | Número de serie de la terminal. | VARCHAR2(20 BYTE) |
| orderId | Identificador de número de transacción. Puede utilizarse posteriormente en reimpresión y cancelación. | VARCHAR2(36 BYTE) |
| preAuth | Preautorización. | VARCHAR(9) |
| preStatus | Preautorización. | NUMBER(15,2) |
| promotion | Número de meses sin intereses en que se parcializó la transacción. | VARCHAR2(20 BYTE) |
| rePrintDate | Versión de la aplicación. | VARCHAR2(100 BYTE) |
| rePrintMark | Identificador interno. | VARCHAR2(100 BYTE) |
| reprintModule | Identificador interno. | VARCHAR2(1 BYTE) |
| cardNumber | Últimos 4 dígitos de la tarjeta leída. | VARCHAR2(50 BYTE) |
| storeName | Nombre del comercio dado de alta. | VARCHAR2(60 BYTE) |
| streetName | Dirección del comercio dado de alta. | VARCHAR2(150 BYTE) |
| storeId | ID del comercio. | VARCHAR(50) |
| ticketDate | Fecha y hora de la transacción. | VARCHAR2(100 BYTE) |
| tipAmount | Monto de propina, en caso de ser enviado. | VARCHAR() |
| tipLessAmount | Monto sin propina. | VARCHAR() |
| transDate | Fecha, 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 |
| transType | Tipo de operación realizada: venta (A), cancelación (V). | VARCHAR2(5 BYTE) |
| transactionCertificate | Información sobre la lectura de la tarjeta. | VARCHAR2(50 BYTE) |
| traceability | Objeto para envío de información adicional. | OBJECT |
Historial de versiones
| Versión | Fecha | Autor(es) | Notas de revisión |
|---|---|---|---|
| 1.0 | 05/05/2025 | Edson Lugo | Versión inicial. |
| 1.1 | 22/05/2025 | Edson Lugo | Se implementa el método para verificación de conexión. |
| 1.2 | 26/05/2025 | Edson Lugo | Se documenta el uso del parámetro bankOnly. |
| 1.3 | 20/06/2025 | Edson Lugo | Se 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. |
Updated 8 days ago
