Actualmente para una integración API y versión de Smart PinPad 2.0, se puede realizar una venta preautorizada y post-autorizadas con ciertas consideraciones a implementar dentro de su proyecto ó punto de venta.
Requerimientos
Para este punto la integración ya debe contar con los apartados iniciales de una integración por API con la terminal y que a continuación se anexan en caso de desconocerse:
1.- https://docs.netpay.com.mx/reference/introducci%C3%B3n-8
2.- https://docs.netpay.com.mx/reference/configuraci%C3%B3n-inicial
3.- https://docs.netpay.com.mx/reference/autorizaci%C3%B3n_1
4.- https://docs.netpay.com.mx/reference/venta-1
8.- https://docs.netpay.com.mx/reference/recibiendo-la-respuesta
La forma de enviar la venta sigue siendo la misma en la documentación mencionada previamente, lo único que cambia
Posterior a la implementación previa, se comparte un ejemplo de petición para enviar hacia la terminal una venta checkIn (Pre-Autorización):
{
"amount": 251,
"serialNumber": "1491234567",
"storeId": "550007",
"folioNumber": "test",
"traceability": {},
"checkIn": true // Bandera que activa Venta CheckIn (Pre-Autorización)
}Campos importantes para el envio de una venta checkIn (Pre-Autorización)
| Nombre campo | Descripción | Tipo de dato | Restricción |
|---|---|---|---|
| serialNumber | Número de serie del dispositivo al que se requiere enviar la petición. | String (Máximo hasta 20 caracteres) | Obligatorio |
| amount | Monto total de la transacción. | Double(15,2) | Obligatorio |
| storeId | Identificador de la tienda asignada al dispositivo. | String (Máximo hasta 38 caracteres) | Obligatorio |
| folioNumber | Número identificador de transacción que puede ser enviado en la solicitud de venta. | String (Máximo hasta 250 caracteres) | Obligatorio |
| traceability | Objeto json para enviar información relevante para el comercio (puede ser algún id de la transacción que posteriormente les servirá para hacer “match” dentro de su sistema. | Object | Opcional |
| checkIn | Activa la bandera de venta por preautorización | Booleano, true , false | Obligatorio |
Obteniendo de respuesta
Al recibir respuesta, como normalmente funciona la integración en la sección https://docs.netpay.com.mx/reference/recibiendo-la-respuesta, llegará hacia su webhook ó servicio web (API) que hayan asignado en las configuraciones de la terminal y tendrá el siguiente formato:
{
"affiliation": "7389108",
"amount": "180.0",
"applicationLabel": "VISA DEBITO",
"arqc": "4FF65E7569A3F12F",
"aid": "A0000000031010",
"authAmount": "180.0",
"authCode": "222222",
"bankName": "BANAMEX",
"bin": "476684",
"cardExpDate": "09/22",
"cardType": "D",
"cardNumber": "0194",
"cardTypeName": "VISA",
"cityName": "SAN NICOLAS DE LOS GARZA NUEVO LEON",
"responseCode": "00",
"folioNumber": "ab33",
"hasPin": false,
"hexSign": "00000100000001DA0000009E000000040800031CFF02FF02D3043B591CAE0AFC111C01C138F96B67A7562F936002A985372DFF00E84DD77A0F2914850EFF021915864419C42FBC6AF2E6464F4BB88B39C91415C2F0DA35EA9AEC9AC6BA9731997685B0EB03C20095860F39B67AC3DC4B7880FF0254390D8A4168EAA2B67B6FB8D760FC833B13B54139D21398820F82B085A91395171B56EC38465586C860B8A0FC58DB28FF02F0FF02FF02EBBEDDE0CDD5F69A1BFF020B559183D780FF0201881080FF02056CFF025C19561040FF02C515CCFF02A544154E205DBEE7C173D809203F8C2C5ED5082A516455DB63B0081FDE97930C8E7951C38EB8CFA7F2061039D6C9E93F0DFD043D06FF02092191EC51DC6AF91ABF0F04EEEFD29AE29FAAAD991CC7654C47FE1465541937428ABCB90940FF0220EF5F924FE68B09E95A628FD7E837EF518BCABD96C38FDDE3A0B8F8A92E1D9B034B40FF02B75AFF0274BABDE55282FF02C73F6768A0FF02849A9B80FF02D015A4FF02FF00BCFF02DE22FF0297FF02FF0014F3A726407725080E6014BBBBA518797DB723B84BC4DA8E8F63CF328A668F7858DC688A59064278A0A95FA183320B7E2C5C8CFB7910FF02069BF60244E5D6EAFEC483D0E2859007F226124F69838031BDAFC122A221BCADEE80FF021B6A1911A6586E8D29F96AC85936CB36995C9458E975DCFF02FF02FF02FF02FF02FF02FF02FF02942EB5C5FE4D9724297AFCB852879391D43B859A8B78FF02056648C1783F5FB1458D41C474330B587ADC9DD266C2D745B2D1D015713634713022ECD71618FF025EA15CA37A767850B086607F6C24804723360ABCBAC5DFEC8B5964614C79184F2E2745E6A4AB90F0FF020A2A0B0C139303E0FF02FF02FF02",
"isQps": 0,
"isRePrint": false,
"message": "Transacción exitosa",
"moduleCharge": "11",
"moduleLote": "1",
"customerName": " PREALTA / DEBITO ",
"terminalId": "1491041680",
"orderId": "250113153656-1491041680",
"preAuth": "1",
"preStatus": 0,
"promotion": "00",
"rePrintDate": "2.0.p.p_20240729",
"rePrintMark": "VISA",
"reprintModule": "C",
"rrnNumber": "011315365660",
"spanRoute": "0194",
"storeName": "qa2",
"streetName": "ROJO",
"ticketDate": "ENE. 13, 25 15:36:54 ",
"tipAmount": "0.0",
"tipLessAmount": "180.0",
"traceability": {},
"transDate": "2025-01-13 15:36:56.CST",
"transType": "PRE",
"transactionCertificate": "55A6049550328013",
"transactionId": "4EE0C597-5E2D-5586-3230-C8493F713936"
}
Para transacciones checkIn(Pre-Autorizadas) el campo transType debe regresar con valor "PRE" junto con el campo preAuth con valor "1".
Campos al recibir la respuesta.
| Nombre 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 con todo y propina. | NUMBER(15,2) |
| 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 | Representa el nombre del tipo de marca de la tarjeta, Visa, Master Card, etc. | VARCHAR2(250 BYTE) |
| cityName | Ciudad con la que se dió 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 se puede tomar 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. | false o 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. | VARCHAR2(1 BYTE) |
| message | Mensaje que indica el estatus de la transacción. Puede indicar si esta fue aceptada o declinada y por qué motivo. | VARCHAR2(200 BYTE) |
| moduleCharge | Identificador interno. | VARCHAR2(20 BYTE) |
| moduleLote | Identificador interno. | NUMBER (9) |
| customerName | Nombre del tarjeta habiente. | VARCHAR2(100 BYTE) |
| terminalId | Número de serie de la terminal. | VARCHAR2(20 BYTE) |
| orderId | Identificador de número de transacción. Puede ser utilizado posteriormente en reimpresión y cancelación. | VARCHAR2(36 BYTE) |
| preAuth | Pre-autorización. | NUMBER (9) |
| preStatus | Pre-autorización / Post-autorización | NUMBER(15,2) |
| promotion | Indica el número de meses sin intereses en que una transacción fue parcializada. | VARCHAR2(20 BYTE) |
| rePrintDate | Indica la 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) |
| ticketDate | Fecha y hora de la transacción. | VARCHAR2(100 BYTE) |
| tipAmount | Indica el monto para propina, en caso de ser enviado. | NUMBER |
| tipLessAmount | Indica el monto menos propina. | NUMBER(15,2) |
| transDate | Fecha y hora de la transacción. | DATE |
| transType | Indica el 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 |
| TransactionId | Identificador único de la transacción, valor clave para realizar el check out, recomendamos guardar este valor en el sistema del cliente . | String |
CHECKOUT POR MEDIO DE API
La URL del servicio de CHECK-OUT será la siguiente:
https://DOMINIO_PROPORCIONADO_POR_NETPAY/checkio/api/check-out
El endpoint tendrá las siguientes características:
- Método: POST
- Data type de envío: JSON
- Seguridad: Api-Key
Netpay será el encargado de proporcionar la api-key necesaria para poderse comunicar con el servicio en el ambiente de sand-box y posteriormente productivo. (La url por la que se comunicará con dicho servicio cambiará en cada escenario).
La URL y el API Key debe compartirse por correo posterior a la solicitud realizada al equipo de integraciones de NetPay.
La api-key será única por COMPANY y deberá ingresarse en el HEADER de la petición en el campo de Authorization:
Las api-keys se generarán por cada COMPANY que el cliente requiera y solamente podrá ser usada para los STORES que pertenezcan al COMPANY.
El body del servicio al ejecutar el request se deberá presentar como a continuación:
| Campo | Tipo | Descripción |
|---|---|---|
| storeId | Long | Identificador único de la unidad transaccional. |
| transactionId | String | Identificador único de la transacción, se obtendrá por medio del servicio de reportes para obtener las transacciones de un COMPANY. |
| totalAmount | Double | Cantidad por la cual se realizará el cierre del check-out. |
Respuestas del servicio
202 Accepted - Code 00
Indica que la transacción fue aprobada con éxito.
- message: Mensaje del servicio indicando lo que sucedió con la petición. [STRING]
- code: Código de respuesta del servicio. [STRING]
- transactionId: Identificador único de la nueva transacción realizada. [STRING]
- trxResponse: Respuesta del procesamiento de la transacción. [STRING]
202 Accepted - Code 05
Indica que la transacción ya fue procesada por lo tanto se generó un check-out para el check-in que se desea cerrar y ya no es posible volver a procesarlo nuevamente.
409 Conflict - Code 04
Indica que el servicio no pudo encontrar el check-in con el transactionId que se utilizó.
409 Conflict - Code 06
Indica que el STORE proporcionado no tiene la operativa check-in / check-out habilitada por el equipo de Netpay.
409 Conflict - Code 08
Indica que es un error de parte de Netpay y debe contactarse con el equipo de soporte para revisión del caso.
409 Conflict - Code 09
Indica que la operativa sólo permite que el check-out se pueda cerrar si no supera su monto original más el 20%.
401 UnAuthorized - No Code
Indica que el STORE proporcionado no tiene permisos con el api-key que se utilizó.