Diagrama de flujo de venta normal
Funciones generales
Obtener Operaciones u operativas (Get Operations)
La función getOperations
recupera una lista de operaciones o servicios disponibles que la terminal de Pagando Check puede realizar.
Uso
Este método se debe invocar cuando se necesita obtener la lista actualizada de operaciones que la terminal puede realizar.
Callback: GetOperationsCallback
- Descripción: Callback utilizado para recibir los resultados de la solicitud de operaciones disponibles.
- Métodos:
onSuccessful
: Este método se invoca cuando se recupera exitosamente la lista de operaciones.- Parámetros:
terminalOperations
(List<String>?): Una lista de cadenas que representan las operaciones disponibles en la terminal.
- Descripción: Se llama cuando se obtiene exitosamente la lista de operaciones disponibles en la terminal.
- Retorno: No retorna un valor, pero proporciona la lista de operaciones disponibles.
- Parámetros:
onError
: Este método se invoca cuando ocurre un error durante la solicitud de operaciones.- Parámetros:
error
(ErrorResponse): Un código y mensaje de error opcional que describe el fallo.code
código de errormessage
mensaje de error
- Descripción: Se llama cuando hay un error en el proceso de obtener las operaciones disponibles.
- Retorno: No retorna un valor, pero proporciona información sobre el error ocurrido.
- Parámetros:
fun getOperations() {
checkServices.getOperations(
object : GetOperationsCallback.Stub() {
override fun onSuccessful(terminalOperations: List<String>?) {
// Lógica a seguir cuando se obtiene la lista de operaciones
Log.i("Client.getOperations", Gson().toJson(terminalOperations))
}
override fun onError(error: ErrorResponse) {
Log.e("getOperations", error.code)
}
}
)
}
CheckServices checkServices = CheckServices.getInstance(this);
checkServices.getOperations(new GetOperationsCallback.Stub() {
@Override
public void onSuccessful(List<String> terminalOperations) {
// Success
}
@Override
public void onError(ErrorResponse error) {
Log.d("getOperations", error.code );
}
});
Listado de Operativas
String | Operativa | Descripción |
---|---|---|
SELL | Venta | Venta normal, se requiere monto, autenticación de tarjetahabiente y se genera un ticket con detalles de la transacción. |
SALE_TIP | Venta con propina | Venta con propina, se requiere monto, se suma la propina, autenticación de tarjetahabiente y se genera un ticket con detalles de la transacción. |
CANCEL | Cancelación | Usando la misma tarjeta el mismo día, se cancela la compra generando una nueva transacción marcada como cancelación** |
REFUND | Devolución | Devolución total o parcial de una compra, se realiza el mismo día de la compra, usando el folio o la tarjeta.** |
DEFERRED_PAYMENT | Pagar después | Venta con promoción, utilizado para mandar una venta con pagos diferidos (Meses sin intereses, meses con intereses y pagar después) |
CHECK_IN | Check In | Operación para la apertura de una cuenta en hotelería o renta de autos. Se requiere del monto y tarjeta presente. Esta operación genera un folio y un registro de operación visible en el panel de administración de Pagando Check. |
CHECK_OUT | Check Out | Cierre de una cuenta en hotelería o renta de autos. Puede ser por un monto parcial o hasta 20% más del Check in. Se requiere únicamente el folio del Check In original. En caso de ser igual al monto del check in, se debe cancelar el checkin y realizar una venta normal por el total de dicho Check In. |
REAUTHORIZATION | Reautorización | Se utiliza para ampliar el monto base de una operación de Check In por un monto mayor al 20%. Aún así, es necesario realizar un Check out para finalizar la cuenta. |
PRE_SALE | Preventa | Operación para la apertura de una cuenta para restaurant. Se requiere del monto y tarjeta presente. Esta operación genera un folio y un registro de operación visible en el listado de Preventas |
PRE_SALE_CLOSING | Cierre de preventa | Cierre de una cuenta para restaurant. Puede ser hasta por un 20% más de la preventa anteriormente autorizada. Se requiere únicamente el folio de la preventa. |
SALE | Sale | Operativa auxiliar, no usada actualmente |
Leer Tarjeta
La función readCard
se utiliza para leer la información de una tarjeta en la aplicación Pagando Check. A continuación, se describen los detalles de la función y se proporciona un ejemplo de su uso.
Nota: Requiere inicialización de llaves
Parámetros
nipPagandoView
:NipPagandoView
- Descripción: La vista utilizada para procesar y mostrar el NIP (Número de Identificación Personal) en la interfaz de usuario.
- Ejemplo:
nipPagandoView
amount
:Double
- Descripción: El monto asociado a la transacción actual.
- Ejemplo:
amount.value
terminalOperation
:TerminalOperation
- Descripción: La operación terminal asociada a la transacción actual (por ejemplo: SALE, SELL, SALE_TIP, CANCEL, REFUND, etc.).
- Ejemplo:
_terminalOperation.value
Callback: ReadCardCallback
- Descripción: Callback utilizado para recibir los resultados de la lectura de la tarjeta.
- Métodos:
onError
: Este método se invoca cuando ocurre un error durante la lectura de la tarjeta.- Parámetros:
error
(ErrorResponse): Un código y mensaje de error opcional que describe el fallo.code
código de errormessage
mensaje de error
- Descripción: Se llama cuando hay un error en el proceso de lectura de la tarjeta.
- Retorno: No retorna un valor, pero proporciona información sobre el error ocurrido.
- Parámetros:
onSuccessful
: Este método se invoca cuando la lectura de la tarjeta se completa exitosamente.- Parámetros:
typeCard
(Int): El tipo de tarjeta leído.
- Descripción: Se llama cuando la lectura de la tarjeta se ha completado satisfactoriamente.
- Retorno: No retorna un valor, pero proporciona información sobre la tarjeta leída.
- Parámetros:
onMessage
: Este método se invoca para proporcionar mensajes informativos durante el proceso de lectura de la tarjeta.- Parámetros:
message
(String): El mensaje informativo.
- Descripción: Se llama para proporcionar información adicional o mensajes durante la lectura de la tarjeta.
- Retorno: No retorna un valor, pero proporciona información adicional.
- Parámetros:
onActionNip
: Este método se ejecuta cuando la tarjeta requiere que el usuario ingrese el NIP- Parámetros:
message
(String): El mensaje de la captura de NIP.
- Descripción: Se llama para procesar acciones específicas relacionadas con el NIP durante la lectura de la tarjeta.
- Retorno: No retorna un valor, pero proporciona información adicional.
- Parámetros:
onApplicationSelection
: Este método se invoca cuando es necesario que el usuario seleccione una aplicación específica (existen tarjetas con varios métodos de entrada).- Parámetros:
apps
(Array<String>): Arreglo de nombres de aplicaciones entre las cuales el usuario debe seleccionar.selectAppCallback
(SelectAppCallback): Callback para manejar la selección de la aplicación.
- Descripción: Se llama cuando es necesario que el usuario seleccione una aplicación específica de la tarjeta.
- Retorno: No retorna un valor, pero indica que se espera la selección de una aplicación.
- Parámetros:
/*
Declara una variable de solo lectura llamada
**checkServices** de tipo **CheckServices** y le asigna
la instancia de **CheckServices** obtenida mediante
el llamado al método **getInstance(context)**.
*/
val checkServices: CheckServices = CheckServices.getInstance(App.appContext)
/*
Llamada de la función readCard que responde con un
ReadCardCallback que podría tener varios métodos,
incluyendo onError, onSuccessful, onMessage,
onActionNip y onApplicationSelection.
*/
checkServices.readCard(
nipPagandoView,
amount.value,
_terminalOperation.value.name,
object : ReadCardCallback.Stub() {
override fun onError(error: ErrorResponse) {
Log.e("readCard", error.code)
}
override fun onSuccessful(typeCard: Int) {
_readCardMessage.value = "Puede retirar su tarjeta."
when (_terminalOperation.value) {
SALE, SELL, SALE_TIP, CANCEL, REFUND, CHECK_IN, CHECK_OUT, REAUTHORIZATION,
PRE_SALE, PRE_SALE_CLOSING, REVERSE, QPS -> makePayment(callback)
DEFERRED_PAYMENT -> getPromotions(callback)
}
}
override fun onMessage(message: String) {
_readCardMessage.value = message
}
override fun onActionNip(message: String?) {
nipPagandoView.proccessMessage(message)
}
override fun onApplicationSelection(
apps: Array<String>?,
selectAppCallback: SelectAppCallback?
) {
MainActivity.instance!!.runOnUiThread {
AlertDialog.Builder(MainActivity.instance)
.setTitle("Select Application")
.setCancelable(false)
.setNegativeButton(
"Cancel"
) { dialog, which ->
dialog.dismiss()
selectAppCallback!!.cancel()
}
.setItems(apps) { dialog, which ->
dialog.dismiss()
selectAppCallback!!.selectApp(which)
}
.show()
}
}
})
CheckServices checkServices = CheckServices.getInstance(this);
checkServices.readCard(nipPagandoView, amount, operationType, new ReadCardCallback.Stub() {
@Override
public void onError(ErrorResponse error) {
Log.d("readCard", error.code );
}
@Override
public void onSuccessful(int typeCard) {
// Success
}
@Override
public void onMessage(String message) {
Log.d("Message:", message)
}
@Override
public void onActionNip(String message) {
nipPagandoView.proccessMessage(message);
}
@Override
public void onApplicationSelection(String[] apps, SelectAppCallback selectAppCallback) {
ReadCardView.this.runOnUiThread(() -> new AlertDialog.Builder(ReadCardView.this)
.setTitle("Select Application")
.setCancelable(false)
.setNegativeButton("Cancel", (dialog, which) -> dialog.dismiss())
.setItems(apps, (dialog, which) -> dialog.dismiss())
.show());
}
});
Marca de la tarjeta
La función getCardBrand
se utiliza para obtener datos necesarios para el proceso de compra, como lo son datos específicos de la tarjeta y token en potencia
Callback GetCardBrandCallback
:
Descripción Callback: Callback utilizado para recibir datos de la tarjeta
- Metodos:
OnSuccessful
brand
marca de la tarjetaBIN
Numero de identificaciónaccountingNature
Naturaleza de la cuentaidempotencyToken
token de identificación en potencia
OnError
- Parámetros:
error
(ErrorResponse): Un código y mensaje de error opcional que describe el fallo.code
código de errormessage
mensaje de error
- Parámetros:
val checkServices: CheckServices = CheckServices.getInstance(App.appContext)
checkServices.getCardBrand(object: GetCardBrandCallback.Stub() {
override fun onSuccessful(cardBrand: CardBrand?) {
// Datos de la tarjeta
}
override fun onError(errorResponse: ErrorResponse?) {
// Manejo de error
}
})
CheckServices checkServices = CheckServices.getInstance(App.getAppContext());
checkServices.getCardBrand(new GetCardBrandCallback.Stub() {
@Override
public void onSuccessful(CardBrand cardBrand) {
// Datos de la tarjeta
}
@Override
public void onError(ErrorResponse errorResponse) {
// Manejo de error
}
});
Estado del token
La función getTokenInPotency
se utiliza para obtener el estado y detalles de un token específico dentro de la aplicación.
Parámetros
- token (String): El token que se desea consultar en el sistema.
Callback TokenStatusCallback
:
- Descripción: Callback utilizado para recibir los resultados de la consulta del token.
- Metodos
OnSuccessful
- Parametros:
status
(String)order
(TokenStatusOrder)folio
folio de la transacciónauthCode
código de autorizacióncurrency
monedacardBrand
Marca de la tarjetaoperationStatus
Estado de la operaciónaccountType
Tipo de cuentaconcept
Conceptocreated_at
fecha de creaciónamount
Cantidadlast4
Ultimos 4 dígitos de la tarjetaemvType
tipo de emvisRecurrentPaymet
Es pago recurrenteopeationType
Tipo de operaciónresponseCode
Código de respuestaresponseDescription
Descripción de la respuesta
- Funcionalidad: Se llama cuando la consulta del token se completa exitosamente, proporcionando estado y detalles asociados.
- Retorno: No tiene retorno
- Parametros:
OnError
- Parámetros:
error
(ErrorResponse): Un código y mensaje de error opcional que describe el fallo.code
código de errormessage
mensaje de error
- Parámetros:
/*
Declara una variable de solo lectura llamada
**checkServices** de tipo **CheckServices** y le asigna
la instancia de **CheckServices** obtenida mediante
el llamado al método **getInstance(context)**.
*/
val checkServices: CheckServices = CheckServices.getInstance(context)
/*
Llamada de la función getTokenInPotency que recibe un token como parámetro.
Responde a un TokenStatusCallback que incluye dos métodos: onSuccessful y onError.
*/
checkServices.getTokenInPotency(token, object : TokenStatusCallback.Stub() {
// Método que se invoca cuando la consulta del token se completa exitosamente
override fun onSuccessful(status: String?, order: TokenStatusOrder?) {
// Obtiene status del token
}
// Método que se invoca cuando hay un error en la consulta del token
override fun onError(error: ErrorResponse) {
// Responde un error
}
})
Realizar Pago
La función makePayment
se utiliza para iniciar el proceso de pago a través del dispositivo de Pagando Check. Esta función es esencial para completar transacciones que implican la transferencia de fondos, validación de tarjetas y aplicación de promociones si están disponibles.
Nota: Requiere inicialización de llaves
Parámetros
callback
:(String) -> Unit
- Descripción: Un callback que se invoca con una ruta de navegación dependiendo del resultado del proceso de pago.
Callback: MakePaymentCallback
- Descripción: Callback utilizado para recibir los eventos y estados durante el proceso de pago.
- Métodos:
onError
: Este método se invoca cuando ocurre un error durante el proceso de pago.- Valores:
error
(ErrorResponse): Un código y mensaje de error opcional que describe el fallo.code
código de errormessage
mensaje de error
- Descripción: Se llama cuando hay un error en el proceso de pago.
- Retorno: Actualiza el estado de
_message
con el código de error.
- Valores:
onPaymentSuccess
: Este método se invoca cuando el pago se completa exitosamente.- Valores:
paymentResponse
(PaymentResponse?): Contiene los detalles del pago realizado.
- Descripción: Se llama cuando el pago se realiza exitosamente.
- Retorno: Actualiza el estado de
_paymentResponse
y_message
con los detalles del pago exitoso y utiliza elcallback
para navegar a la pantalla de impresión de ticket.
- Valores:
onSignatureRequired
: Este método se invoca cuando se requiere la firma del cliente para completar el pago.- Descripción: Se llama cuando el proceso de pago requiere la firma del cliente.
- Retorno: Actualiza el estado de
_message
con un mensaje indicando que se requiere firma y utiliza elcallback
para navegar a la pantalla de firma.
fun makePayment(callback: (String) -> Unit) {
val checkServices: CheckServices = CheckServices.getInstance(context)
checkServices.makePayment(
object : MakePaymentCallback.Stub() {
override fun onError(error: ErrorResponse) {
Log.e("makePayment", error.code)
}
override fun onPaymentSuccess(paymentResponse: PaymentResponse?) {
_paymentResponse.value = paymentResponse!!
_message.value = "Pago exitoso: " + paymentResponse.folio
callback(NavRoutes.salePrintTicketView.route)
}
override fun onSignatureRequired() {
_message.value = "Requiere firma: abrir pantalla para dibujar firma"
callback(NavRoutes.saleSignatureView.route)
}
})
}
El modelo PaymentResponse
encapsula los detalles y el estado de una transacción de pago. A continuación, se documentan las propiedades de este modelo:
Propiedades
responseCode
(String
): Código que indica el resultado de la transacción.description
(String
): Descripción textual del resultado de la transacción.accountType
(String
): Tipo de cuenta asociada con la tarjeta.ARQC
(String
): Cryptograma de solicitud de autorización (Authorization Request Cryptogram).AID
(String
): Identificador de la aplicación de la tarjeta (Application Identifier).last4
(String
): Últimos cuatro dígitos del número de la tarjeta.brand
(String
): Marca comercial asociada con la tarjeta o transacción.folio
(String
): Folio único de la transacción.amount
(String
): Importe por el que se realizó la transaccióntransactionTime
(String
): Fecha y hora de la transacción.pinEntry
(boolean
): Identifica si para la transacción fue introducido el PIN de verificación de la tarjetaemvType
(String
): Identifica el tipo de lector de tarjeta que se utilizo al procesar la transacción.requireSignature
(boolean
): Indica si la transacción requiere firma del cliente.authCode
(String
): Código de autorización generado por la entidad emisora de la tarjeta.traceNumber
(String
): Número de seguimiento de la transacción.retrievalReference
(String
): Número de referencia para la recuperación de lastatus
(String
): Estado de la transacción.mustReloadKeyNow
(boolean
): Indica si es necesario recargar la clave inmediatamente.mustReloadKeySoon
(boolean
): Indica si será necesario recargar la clave pronto.employee
(String
): Identificador del empleado que realizó o gestionó la transacción.merchantIdCode
(String
): Número de identificación único del comercio (Afiliación Bancaria)tipAmount
(Double
): Cuanto fue agregado de propina.operationType
(String
): Tipo de operación realizada.
Establecer Firma
La función setSignature
se utiliza para enviar la firma digital capturada del cliente a los servicios de Pagando Check como parte del proceso de finalización de una transacción. Esta firma es crucial para confirmar la autorización de la transacción por parte del cliente.
Parámetros
base64String
:String
- Descripción: La firma del cliente codificada en base64.
- Ejemplo:
"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...=="
callback
:() -> Unit
={}
- Descripción: Un callback opcional que se invoca después de que la firma ha sido enviada y procesada exitosamente.
- Valor por defecto: Un callback vacío, indicando que no hay acciones adicionales a realizar después del proceso.
Callback: SignatureCallback
- Descripción: Callback utilizado para recibir los eventos y estados durante el proceso de envío de la firma.
- Métodos:
onError
: Este método se invoca cuando ocurre un error durante el proceso de envío de la firma.- Parámetros:
error
(ErrorResponse): Un código y mensaje de error opcional que describe el fallo.code
código de errormessage
mensaje de error
- Descripción: Se llama cuando hay un error en el proceso de envío de la firma.
- Retorno: Actualiza el estado de
_message
con el código de error.
- Parámetros:
val checkServices: CheckServices = CheckServices.getInstance(App.appContext)
checkServices.setSignature(base64String,
object : SignatureCallback.Stub() {
override fun onError(error: ErrorResponse) {
Log.e("setSignature", error.code)
}
override fun onSuccessful(paymentResponse: PaymentResponse?) {
// Success
callback()
}
})
CheckServices checkServices = CheckServices.getInstance(this);
checkServices.setSignature(bitmap, new SignatureCallback.Stub() {
@Override
public void onError(ErrorResponse error) {
Log.d("setSignature", error.code );
}
@Override
public void onSuccessful(PaymentResponse paymentResponse) {
// Success
}
});
Obtener Detalles de Transacción por Folio
La función getOperationByFolio
se utiliza para recuperar información detallada de una transacción específica mediante su folio. Es crucial para realizar seguimientos y validaciones de transacciones individuales.
Parámetros
folio
:String
- Descripción: El identificador único de la transacción que se desea recuperar.
- Ejemplo:
"FOL123456789"
context
:Context
- Descripción: El contexto actual de la aplicación. Se utiliza para acceder a recursos y datos específicos del entorno de la aplicación.
Callback: TransactionByFolioCallback
- Descripción: Callback utilizado para recibir los detalles de la transacción solicitada.
- Métodos:
onSuccessful
: Este método se invoca cuando la información de la transacción se recupera exitosamente.- Valores:
paymentResponse
(TransactionFolioResponse
?): Contiene los detalles de la transacción recuperada, incluyendo:accountType
(String
): Tipo de cuenta asociada con la tarjeta.ARQC
(String
): Cryptograma de solicitud de autorización (Authorization Request Cryptogram).AID
(String
): Identificador de la aplicación de la tarjeta (Application Identifier).BIN
(String
): Bin de la tarjeta que realizó la operación a 6 dígitosBIN8
(String
): Bin de la tarjeta que realizó la operación a 8 dígitoslast4
(String
): Últimos cuatro dígitos del número de la tarjeta.brand
(String
): Marca comercial asociada con la tarjeta o transacción.folio
(String
): Folio único de la transacción.amount
(String
): Importe por el que se realizó la transacción.status
(String
): Estado de la transacción.emvType
(String
): Identifica el tipo de lector de tarjeta que se utilizo al procesar la transacción.authCode
(String
): Código de autorización generado por la entidad emisora de la tarjeta.pinEntry
(boolean
): Identifica si para la transacción fue introducido el PIN de verificación de la tarjetadescription
(String
): Descripción textual del resultado de la transacción.merchantIdCode
(String
): Número de identificación único del comercio (Afiliación Bancaria)transactionTime
(String
): Fecha y hora de la transacción.requireSignature
(boolean
): Indica si la transacción requiere firma del cliente.operationType
(String
): Tipo de operación realizada.
- Descripción: Se llama cuando se obtiene exitosamente la información de la transacción.
- Valores:
onError
: Este método se invoca cuando ocurre un error durante la solicitud de la transacción.- Valores:
error
(ErrorResponse): Un código y mensaje de error opcional que describe el fallo.code
código de errormessage
mensaje de error
- Descripción: Se llama cuando hay un error en el proceso de recuperar la transacción.
- Retorno: Proporciona información sobre el error ocurrido.
- Valores:
fun getOperatationByFolio(folio: String, context: Context){
val checkServices: CheckServices = CheckServices.getInstance(context)
viewModelScope.launch {
checkServices.transactionByFolio(folio, object: TransactionByFolioCallback.Stub(){
override fun onSuccessful(paymentResponse: TransactionFolioResponse?) {
// Lógica a seguir cuando la petición es exitosa
}
override fun onError(error: ErrorResponse) {
Log.e("getOperatationByFolio", error.code)
}
)
}
}
CheckServices checkServices = CheckServices.getInstance(this);
checkServices.transactionByFolio(folio, new TransactionByFolioCallback.Stub() {
@Override
public void onSuccessful(TransactionFolioResponse paymentResponse) {
// Success
}
@Override
public void onError(ErrorResponse error) {
Log.d("transactionByFolio", error.code );
}
});