Reimpresión por folio en integración SDK
Esta funcionalidad actualmente es obligatoria de implementar en la integración con su punto de venta, ya que ayudará como un mecanismo de defensa ante contingencias que impidan no recibir la respuesta y sea un modo de recuperación del estatus de una transacción.
La reimpresión por folio tiene 2 finalidades:
- Imprimir una copia en papel de transacciones aprobadas y transacciones declinadas (excepto reversos).
- Utilizarlo como un medio de consulta para recuperar estatus de transacciones perdidas para transacciones aprobadas/declinadas/reversadas/pendientes por reversar.
Requisitos para la reimpresión por folio
- Contar con el SDK de NetPay, versión 1.1.9 o superior.
- Tener instalada la Smart PinPad Dev 2.0_20240729 para pruebas, o la Smart PinPad 2.0 para producción.
- Para recuperar la respuesta de una venta por medio del folio, es indispensable haber enviado este campo previamente en la transacción de venta inicial.
- Contar con un folio único, tanto para transacciones aprobadas como para declinadas.
Campos utilizados para la reimpresión
| Nombre campo | Descripción | Tipo de dato |
|---|---|---|
| folioId | Número identificador de transacción que puede ser enviado en la solicitud de venta y que debe ser un valor único interno del sistema punto de venta del comercio. | String (Máximo hasta 250 caracteres) |
| orderId | Identificador único de transacción con NetPay. Se genera en una venta exitosa y puede ser utilizado posteriormente en reimpresión y cancelación. | String (Máximo hasta 250 caracteres) |
Envío del folio en la venta original
Para que la reimpresión por folio funcione correctamente, el campo folioId debe enviarse desde la transacción de venta inicial. A continuación se muestra un ejemplo de una venta enviando el folio:
fun callSale() {
val sale = SaleRequest("mx.com.netpay.demosdk", amount)
sale.folioId = folio.text.toString() // Se envía el folio en la venta
try {
smartApi.doTrans(sale, false, disabledPrint.isChecked)
} catch (e: SmartApiException) {
Toast.makeText(this, e.message, Toast.LENGTH_LONG).show()
}
}
Es importante tomar en cuenta que la venta previa debió haberse generado con el folio del sistema punto de venta del comercio.
Implementación de reimpresión por folio (ReprintRequest)
A partir de la versión Smart PinPad 2.0 en adelante y SDK v1.1.9, es posible consultar el estado de una transacción invocando la reimpresión (ReprintRequest) desde el SDK de NetPay. A continuación se muestra un ejemplo de la llamada al SDK para solicitar la reimpresión de un ticket mediante el folio:
// Se inicializa la instancia de SmartApi, usando el activity actual como parámetro
private val smartApi = SmartApiFactory.createSmartApi(this)
fun callReprintByFolio() {
val orderId = orderIdTE.text.toString() // Valor de referencia
val folioId = folio.text.toString()
val sale = ReprintRequest("mx.com.netpay.demosdk", orderId, folioId = folioId)
try {
smartApi.doTrans(sale, false, disabledPrint.isChecked)
} catch (e: SmartApiException) {
Toast.makeText(this, e.message, Toast.LENGTH_LONG).show()
}
}
Para que la búsqueda por folio se realice correctamente, es importante enviar únicamente el folio como parámetro. Si se envían elorderIdy el folio de forma simultánea, la funcionalidad dará prioridad alorderIdy el proceso de recuperación no concluirá con éxito. El campoorderIddebe permanecer vacío, enviando únicamente el folio.
Recibiendo la respuesta del SDK
A continuación se muestra un ejemplo de cómo recibir la respuesta de esta operación. En este caso, la validación se realiza en el hook onActivityResult / onActivityCallResult del activity:
override fun onActivityCallResult(requestCode: Int, resultCode: Int, data: Intent?) {
when (requestCode) {
Constants.REPRINT_REQUEST -> {
val response = smartApi.onResult(requestCode, resultCode, data) as ReprintResponse
if (response.success) {
// Cuando success == true, significa que se encontraron
// registros de la transacción solicitada
if (response.reprintModule == "C") {
// reprintModule == "C" indica que se trata de una
// transacción identificada como completada
}
if (response.reprintModule == "D") {
// reprintModule == "D" indica que se trata de una
// transacción identificada como declinada
}
if (response.reprintModule == "RV") {
// reprintModule == "RV" indica que se trata de una
// transacción identificada como reversada
}
if (response.reprintModule == "PRV") {
// reprintModule == "PRV" indica que se trata de una
// transacción identificada como pendiente de reverso
}
} else {
// Cuando success == false, significa que no existen
// registros de esa transacción. Esto puede deberse a que
// la transacción no existe o a que se interrumpió antes
// de completarse en línea.
// P. ej.: cancelación del usuario, red no disponible, etc.
}
}
}
}
El campo que debe validarse para conocer el estatus de una transacción esreprintModule. A continuación se detallan los valores posibles y su significado.
Es de vital importancia no basarse en el camporesponseCodepara validar el resultado de una reimpresión, ya que al tratarse de una operación de tipo consulta, este campo devolverá un valor genérico que no refleja el estatus real de la transacción. El camporeprintModulees el único que debe utilizarse para esta validación.
| Respuesta | Significado | Descripción |
|---|---|---|
| reprintModule: C y transtype: A | Transacción aprobada | Confirma que la transacción se encuentra aprobada. Debe considerarse el tipo de transacción transtype: A. |
| reprintModule: C y transtype: V | Transacción cancelada | La transacción se encuentra cancelada cuando se presenta la combinación reprintModule: C y transtype: V. |
| reprintModule: D | Transacción declinada | La transacción fue declinada por una regla de fraude o por el emisor. |
| reprintModule: RV | Transacción reversada | La transacción fue reversada exitosamente y, por lo tanto, no debe considerarse como exitosa. |
| reprintModule: PRV | Transacción pendiente de reverso | Transacción programada para ser reversada en una siguiente transacción. |
Cuando una transacción está reversada, en pantalla aparecerá el siguiente mensaje:
Excepciones en la funcionalidad de reimpresión por folio.
- Al utilizar un
folioIdrepetido, la reimpresión mostrará la última transacción realizada con el folio ingresado. - Al ingresar un
folioIdno existente, la terminal mostrará un mensaje de "No se encontraron datos". - Al consultar una transacción que presentó error de conexión durante la venta original, la respuesta de la reimpresión por
folioIdindicará una transacción pendiente de reverso. - Existen declinaciones locales en terminal que pueden mostrar un mensaje, "No se encontraron datos".
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.
Para más información sobre problemas de comunicación y/o reversos, se puede consultar la siguiente documentación: Manejo de reversos para integración SDK
Updated 10 days ago
