Esta integración nació para poder transaccionar con diferentes usuarios (storeIds) en una misma terminal, siempre y cuando los storeIds (usuarios) estén dados de alta dentro de un grupo Smart Accounts.
Requisitos previos a Smart Accounts:
Para poder realizar esta implementación es importante seguir previamente los siguientes requisitos:Configuración inicial de la terminal. (netpay.com.mx)
Requistos para Smart Accounts:
- Contar con un par de storeIds (de pruebas) que estén dados de alta en un grupo Smart Accounts, normalmente el equipo de integraciones de NetPay les debe ofrecer uno de pruebas durante la sesión de integración o por correo.
- Enviar el parámetro "isSmartAccounts" en la venta.
- Tener logeado uno de los storeIds específicos en la terminal sobre la aplicación Smart PinPad Dev.
Venta
Posterior a los requisitos previos, se podrá enviar una venta con Smart Accounts colocando un campo nuevo llamado "isSmartAccounts" en el request de la venta el cual contendrá un valor del tipo Booleano con valor “true”.
Los storeIds deben tener una configuración especial y estar sobre un grupo smart Accounts para funcionar, de lo contrario esta integración no funcionará.
Los storeIds deben haberse enviado por correo después de comunicarse con el área de integraciones de NetPay.
Endpoint para generar el token (POST):
https://api-154.api-netpay.com/oauth-service/oauth/token
Endpoint para enviar una Venta (POST):
https://api-154.api-netpay.com/integration-service/transactions/sale
Ejemplo de un request body para la venta con smart accounts:
{
"traceability": {},
"amount": 1.01,
"serialNumber": "0821000119", //Número de serie de la terminal de NetPay
"storeId": "XXXXXX", // storeId especial con grupo smart accounts que se les comparte por correo.
"isSmartAccounts":"true", //Bandera obligatoria con valor true para Smart Accounts
"folioNumber":"ejemploFolioÚnico-123" //ID único del POS que identifique a la transacción.
}Respuesta del request de venta:
{
"code": "00",
"message": "Mensaje enviado exitosamente"
}Respuesta final de la venta procesada en la terminal y exitosa:
{
"affiliation": "7286147",
"amount": "5.0",
"applicationLabel": "Debit MasterCard",
"arqc": "16FC4A3B40565EC1",
"aid": "A0000000041211",
"authAmount": "5.0",
"authCode": "222222",
"bankName": "SANTANDER",
"bin": "557909",
"cardExpDate": "10/23",
"cardType": "D",
"cardNumber": "7934",
"cardOrigin": "",
"cardTypeName": "MASTERCARD",
"cityName": "MONTERREY",
"responseCode": "00",
"folioNumber": "TEST-SMART-ACCOUNTS", //Folio único e interno de su punto de venta.
"hasPin": true,
"hexSign": "",
"isQps": 0,
"isRePrint": false,
"message": "Transacción exitosa",
"moduleCharge": "1",
"moduleLote": "1",
"customerName": "DEBITO UNIVERSIDADES /",
"terminalId": "XXXXXXXXXX", //Número de serie de la terminal de NetPay
"orderId": "260106161637-XXXXXXXXXX", //Id de la transacción aprobada
"preAuth": "0",
"preStatus": 0,
"promotion": "00",
"rePrintDate": "2.2.1.3.p.p_20251201",
"rePrintMark": "MASTER",
"reprintModule": "C",
"rrnNumber": "010616178812",
"spanRoute": "7912",
"storeId": "XXXXXX", // Usuario otorgado por correo y que podrá variar al pertenecer al mismo grupo Smart Accounts
"storeName": "F",
"streetName": "AV. INSURGENTES",
"ticketDate": "ENE. 06, 26 11:52:01 ",
"tipAmount": "0.0",
"tipLessAmount": "5.0",
"traceability": {},
"transDate": "2026-01-06 16:16:38.GMT-07:00",
"transType": "A",
"transactionCertificate": "3BFC87378CD0E050",
"transactionId": "6CCEDB1D-1674-1DF8-3E98-7C261561B242"
}Reimpresión de una venta.
Endpoint para reimpresión:
https://api-154.api-netpay.com/integration-service/transactions/reprint
Requerimientos: Tener un order id de una venta
Para realizar una reimpresión usando el servicio de reprint , se debe agregar el campo de isSmartAccount, de lo contrario no hará el cambio de storeId en la terminal, tomando el que actualmente esté configurado de manera predeterminada.
Ejemplo de request de una reimpresión:
}
"traceability": {},
"folioId": "XXXXX-XXXXXXX", //ID único interno del POS enviado en la venta.
"serialNumber": "XXXXXXXXXX", //Número de serie de la terminal de NetPay
"storeId": "XXXXXX", //Usuario compartido por correo
"isSmartAccounts":"true" //Bandera obligatoria en true para smart accounts
}Respuesta del request de reimpresión:
{
"code": "00",
"message": "Mensaje enviado exitosamente"
}Para más información anexamos la sección completa de este tema: Reimpresión por folio de una venta (Integración API)
Cancelación de una venta.
Endpoint de cancelación:
https://api-154.api-netpay.com/integration-service/transactions/cancel
Requerimientos: Tener un order id de una venta y la venta debe ser el mismo día antes de las 8pm hora CDMX.
Para realizar una cancelación del tipo smart Accounts, seria de la misma forma en que se realiza una cancelación por push simple, solamente añadiendo el parámetro isSmartAccount. A continuación se presenta un ejemplo.
Ejemplo de request de una cancelación:
{
"traceability": {
},
"orderId": "200623160129-XXXXXXXXXX",
"serialNumber": "XXXXXXXXXX", //Número de serie de la terminal de NetPay
"storeId": "XXXXXX", //Usuario compartido por correo
"isSmartAccounts":"true" //Bandera obligatoria en true para smart accounts
}Respuesta de request de cancelación
{
"code": "00",
"message": "Mensaje enviado exitosamente"
}Para más información anexamos la sección completa de este tema: Cancelación de una venta (Integración API)
Siguientes Pasos
Anexamos información que podría ser útil posterior a la implementación de Smart Accounts:
Manejo de reversos en terminales (Integración API)
Reimpresión por folio (Integración API)
Certificación de la integración por API
Al concluir la integración (ambiente de pruebas), las credenciales, grupos y storeIds deben gestionarse con su asesor comercial de NetPay ya que requiere dar de alta documentación de la organización para generarse. Debido a ello el equipo de integraciones de NetPay ya NO interviene en este proceso productivo.
Validación y confirmación de grupo Smart Accounts.
A continuación se anexa un servicio que puede ayudarles en producción a confirmar que storeIds pertenecen a 1 grupo Smart Accounts.
- Endpoint del servicio a consumir: https://suite.netpay.com.mx/gateway/integration-service/smart-account/smartAccountLogin
- HTTP Request: POST
Ejemplo de campos a enviar en la petición (Request Body):
{
"storeId":"XXXXXX", // Credenciales que serán otorgadas solo en producción.
"password": "ejemploContraseña" // Credenciales que serán otorgadas solo en producción.
}Es importante no confundir el storeId del grupo smart accounts con los storeIds que tiene dentro del grupo.
Son 2 tipos de credenciales diferentes uno para cada grupo y otro para cada storeId que pertenezca a cada grupo.
Ejemplo de respuesta recibida del servicio (Response Body):
{
"code": "00",
"message": "Transaccion Valida",
"trList": [
{
"name": "SUCURSAL O CAJA 1", //Valores de ejemplo
"storeId": "XXXXXX" //Valores de ejemplo
},
{
"name": "SUCURSAL O CAJA 2", //Valores de ejemplo
"storeId": "XXXXXX" //Valores de ejemplo
}
]
}
Este servicio les ayudará a identificar que storeIds pertenecen a que grupo, de esta forma hacen una doble confirmación antes de enviar una venta a la terminal deseada.