11.1 Requisitos previos antes de implementar las devoluciones.
Las devoluciones en NetPay surgen en caso de que una cancelación no logré realizarse a tiempo en el mismo día antes de las 8pm hora CDMX por lo que si esto sucede, en esta sección, se comparte información para poder ejecutar la API de devoluciones y que no depende completamente de una terminal.
11.1.1 Integración API para realizar una venta con la terminal de NetPay.
Es muy importante que para este punto de la documentación ya se hayan seguido los pasos anteriores necesarios para realizar una integración de una venta desde la terminal.
Si la integración de la venta en terminal es API los pasos serían los siguientes:2.- Configuración inicial de la terminal
3.- Autorización y generación del token
8.- Recibiendo la respuesta de una transacción.
Si la integración de la venta en terminal es SDK, los pasos serían los siguientes:2.- Configuración Inicial de la terminal.
Al implementar el proceso de venta, el campo importante en la respuesta para devoluciones y que debe proceder a almacenarse es el transactionId.
11.1.2 Implementación de API Print Ticket.
Antes de ejecutar una devolución, se debe realizar la implementación de este servicio que actuará después de realizar una venta aprobada, y su objetivo es proporcionar valores adicionales a una transacción.
Este Servicio Print-Ticket no funciona para validar estatus de transacciones por lo que únicamente nos ayudará con el proceso de devoluciones.
Los datos para implementar el servicio de Print Ticket serían los siguientes:
- URL: https://sandbox.api-netpay.com/ticket-sandbox/api/print-ticket
- Metodo HTTP-: POST
- Seguridad: API Key
Netpay será el encargado de proporcionar la API Key y StoreId necesaria para poder comunicarse con el servicio. Este tipo de valores sensibles deben solicitarse con el área correspondiente de NetPay a través de su asesor comercial de NetPay. También pueden solicitarlo o ya deben haberlo recibido por correo ó en una sesión de Google Meet sobre agenda.
A modo de ejemplo se comparte una captura de como agregar este servicio en Postman:
Encabezado con el campo Authorization y valor de API Key.
Este es el body request a agregar:
{
"storeId": XXXXX, //Este valor se envía por correo o pueden solicitarlo al equipo de NetPay
"transactionId": "994FTE45-65D2-F4FB-B36B-2E3DD34AA86D" //Se obtiene en una Venta Aprobada y este valor cambia.
}
| Campo | Tipo | Descripción |
|---|---|---|
| storeId | Long | Identificador único de la unidad transaccional. |
| transactionId | String | Identificador único de la transacción (venta). |
Respuesta al ejecutar el servicio Print Ticket:
{
"message": "Transaccion Valida",
"code": "00",
"transactionType": "A",
"merchantId": "7389108",
"storeName": "Comercio",
"street": "CHV",
"city": "APODACA",
"spanRoute": "**** **** ****1234",
"cardBrand": "VISA/BBVA BANCOMER/Crédito",
"transDate": "2024-10-16 10:37:34.0",
"authCode": "222222",
"acqHostRef": "241017693734-1491130872104240",
"amount": 400.0,
"transactionOwner": "null",
"storeId": XXXXX,
"orderId": "241017693734-1491130872104240",
"status": "Aprobada",
"transactionId": "994FTE45-65D2-F4FB-B36B-2E3DD34AA86D",
"arqc": "69C28EAF5119UFF7",
"aid": "A0000000034010",
"moduleLote": "1",
"moduleCharge": "1",
"terminalId": "1491130872",
"transactionCertificate": "69C28EAF5119UFF7",
"customerName": "null",
"affiliation": "7389108",
"version": "2.0.p.p_20240729"
}El valor importante a guardar es el orderId, junto con el transactionId de la venta. Ambos valores son importantes para realizar el siguiente paso de Devoluciones.
No confundir el orderId de Print-Ticket con el orderId de la venta.Se pueden diferenciar ya que el orderId del Print-Ticket cuenta con más valores.
11.2 Integración de API Devoluciones
Posterior a realizar los pasos anteriores que son muy importantes, ya se debe contar con el transactionId de la venta, y el orderId del servicio Print-Ticket. Posterior a ello ya podemos continuar con esta parte del proceso.
La URL del servicio de devolución será la siguiente:
https://sandbox.api-netpay.com/transaction-154/api/credit-api
El endpoint debe contar con las siguientes características:
- Método HTTP-: POST
- Data type de envío: JSON
- Seguridad: API Key
Netpay será el encargado de proporcionar la API Key y StoreId necesaria para poder comunicarse con el servicio. Este tipo de valores sensibles deben solicitarse con el área correspondiente de NetPay. También pueden solicitarlo o ya deben haberlo recibido por correo ó en una sesión de Google Meet sobre agenda.
Es muy importante considerar que primero se integraría sobre el ambiente de SandBox(Pruebas) ya que los datos para un ambiente productivo (cobros reales) se comparten hasta después de certificar la integración de su sistema.
La API Key será única por COMPANY y únicamente a modo de ejemplo, compartimos captura de la sección de Postman donde se puede agregar:
Postman automáticamente agrega estos valores en el campo Authorization de la sección de HEADER de la petición por lo que a continuación se adjunta un ejemplo:
Si el cambio desean integrarlo directamente en su sistema y no en Postman, debe ir sobre los HEADER de la petición.
Las API Keys se generarán por cada COMPANY que se requiera y solamente podrá ser usada para los StoreIDs que pertenezcan a dicho COMPANY.
El body del servicio para ejecutar el request se deberá presentar de la siguiente forma:
{
"storeId": "XXXXXX", //Este valor se envía por correo o pueden solicitarlo al equipo de NetPay
"transactionId": "994FTE45-65D2-F4FB-B36B-2E3DD34AA86D", //Se obtiene en una Venta Aprobada y este valor cambia.
"orderId": "241017693734-1491130872104240", //Se obtiene en el servicio PRINT TICKET y este valor cambia.
"amount": 400,
"motive": "Prueba Devoluciones"
}
El API Key y storeId de pruebas deben solicitarse con el área correspondiente de NetPay a través de su asesor comercial de NetPay. También pueden solicitarlo o ya deben haberlo recibido por correo ó en una sesión de Google Meet sobre agenda.
A continuación, compartimos el significado y tipo de valor de cada campo:
| Campo | Tipo | Descripción |
|---|---|---|
| storeId | Long | Identificador único de la unidad transaccional. |
| transactionId | String | Identificador único de la transacción (venta). |
| orderId | String | Es el indicador oficial que agrupa toda una orden o eventos de una transacción (venta). |
| amount | Double | Monto de la por la cual se quiere realizar la devolución de la transacción (parcial o total). |
| motive | String | Motivo por el cual se está realizando la devolución. |
Posterior a la implementación, pueden realizar pruebas internas en su sistema y solicitamos por favor puedan agendar un espacio disponible con el área de integraciones de NetPay para certificar esta funcionalidad en conjunto con otras implementadas y que estén relacionadas con NetPay. Para más información se anexa la sección que explica el proceso de Certificación necesario 10.- Certificación de Integracion Terminales NetPay.
Como siguiente paso de la Certificación, se evaluaría la evidencia recolectada y se enviarían los resultados exitosos de la integración junto con la URL productiva (Ambiente), al cual se debe apuntar para realizar el proceso sobre transacciones reales.
Finalmente el API key va ser necesario solicitarse con el equipo de producción de NetPay y que es muy importante contar con ello para que el proceso de devoluciones en ambiente productivo funcione correctamente.
11.3 Respuestas del servicio (API Devoluciones):
A continuación se detalla los campos de respuesta, sus valores y código de error que pueden presentarse durante el flujo de una devolución:
| Campo | Tipo | Descripción |
|---|---|---|
| code | String | Código de respuesta del servicio. |
| message | String | Mensaje del servicio indicando lo que sucedió con la petición. |
| transactionId | String | Identificador único de transacción. |
200 OK - Code 02
Indica que la transacción fue aprobada con éxito.
409 Conflict - Code 29
Indica que no se han enviado los datos de la petición necesarios o se han enviado de forma incorrecta.
409 Conflict - Code 18
Indica que el StoreId proporcionado no tiene la operativa de devoluciones habilitada por el equipo de Netpay.
409 Conflict - Code 20
Indica que no se han encontrado registros con los parámetros enviados.
409 Conflict - Code 24
Indica que el proceso de devolución no puede ser realizada en esta transacción, este puede ser por distintos motivos, los cuales son los siguientes:
- La transacción se encuentra en proceso de aclaración.
- La transacción presenta un contracargo.
- La transacción fue realizada con promoción meses sin intereses.
- El tiempo para devoluciones configurado ha expirado.
- La transacción fue realizada con tarjeta valera.
409 Conflict - Code 21
Indica que se trata de realizar una devolución a una transacción previamente cancelada.
409 Conflict - Code 19
Indica que se trata de realizar una devolución por un monto mayor a la transacción original.
401 UnAuthorized - No Code
Indica que el STORE proporcionado no tiene permisos con el api-key que se utilizó.
