Consultar el historial de transacciones

Obtener el historial de transacciones

El SDK de Clip permite obtener el historial de transacciones que se han realizado.

Las funciones disponibles para trabajar con el historial son las siguientes:

  • search(): permite realizar una búsqueda de transacciones del mismo día y aplicar distintos filtros.
  • detail(): muestra detalles para una transacción individual.
  • refund(): realiza el reembolso de una transacción.

La siguiente tabla muestra los elementos en el objeto de respuesta ClipTransaction que regresan las funciones anteriores:

Elemento

Descripción

Tipo de dato

receiptNumber

Identificador único de la transacción

String

amount

Cantidad del pago

BigDecimal

tip

Cantidad de la propina

BigDecimal

totalAmount

Cantidad total del pago incluyendo propina

BigDecimal

cardType

Tipo de tarjeta utilizada para el pago:  

  • VISA
  • MASTERCARD
  • DISCOVER
  • AMEX
  • JCB
  • CARNET
  • SIVALE
  • UNKNOWN

Object, string

last4

Últimos cuatro dígitos de la tarjeta utilizada para el pago

String

installment

Indica si el pago se difiere en mensualidades

String

walletAmount

Cantidad a pagar con monedero electrónico

BigDecimal

walletType

Tipo de monedero

  • Points
  • Card

Object

walletSubType

Clasificación de la tarjeta de puntos.

Posibles tipos de tarjetas:

  • Visa Tasa Clásica
  • Visa Tradicional Clásica
  • Visa Básica
  • Visa Tasa Baja Oro
  • Visa Tradicional Oro
  • Mc Scotia Travel Platinum
  • MC Scotia Travel Oro - SRP
  • MC Tasa Baja Oro
  • MC Tradicional Oro
  • MC Scotia Travel Clásica
  • MC Tasa Baja Clásica
  • MC Tradicional Clásica
  • MC Scotia Travel World Elite
  • Platinum Infinite Visa
  • Scotia MX Ideal
  • Scotia Rewards Gold

String

merchantInvoiceId

Referencia alfanumérica proporcionada por el vendedor

String

status

Estado de la transacción.

Lista de posibles estados de la transacción:

  • Paid
  • Refunded
  • Cancelled
  • Declined
  • Error

Object, string

currency

Código de divisa para la transacción del pago conforme a ISO 4217

String

paymentDate

Fecha de creación del pago

Date

location

Objeto que contiene la información de ubicación

Object

longitude

Coordenada de longitud para la ubicación de la transacción

Double

latitude

Coordenada de latitud para la ubicación de la transacción

Double

Buscar transacciones en el historial

Implementa la siguiente función para buscar transacciones en el historial:

ClipHistory.search(SearchParamsRequest.byDate(date: Date, page: Int), object : ClipHistoryListener.OnSearchSuccessListener {
                override fun onSearchSuccess(response: List<ClipTransaction>?) {
                }
            }, , object : ClipHistoryListener.OnErrorListener {
                override fun onError(error: StatusCode.ClipError) {
                }
            })

ClipHistory.search(SearchParamsRequest.byDate(Date date, int page), new ClipHistoryListener.OnSearchSuccessListener() {
            @Override
            public void onSearchSuccess(@Nullable List<ClipTransaction> list) {
            }
        }, new ClipHistoryListener.OnErrorListener() {
            @Override
            public void onError(@NotNull StatusCode.ClipError clipError) {
            }
        });

La siguiente tabla incluye una descripción para los parámetros de la función:

Elemento

Descripción

SearchParamsRequest

Función de búsqueda

.byCardNumber

Realiza la búsqueda por el número de tarjeta utilizada para el pago

.byDate

Realiza la búsqueda por la fecha del pago

.byDateRange

Realiza la búsqueda por un rango de fechas definido

.byReceiptNumber

Realiza la búsqueda por el número de recibo que identifica al pago

CardNumber: El objeto CardNumber está compuesto por los últimos 4 dígitos que aparecen en la tarjeta.

Elemento

Descripción

Tipo de dato

value

L os últimos 4 dígitos que aparecen en la tarjeta.

El regex que se valida es: ^\d{0,4}$

De no cumplir con el formato especificado, se regresará una excepción de tipo:  InvalidParameterFormat.

String

ReceiptNumber: El objeto ReceiptNumber representa el número de recibo generado por Clip al concluir una transacción de manera exitosa.

Elemento

Descripción

Tipo de dato

value

Número de recibo generado por Clip.

El regex que se valida es: ^[a-zA-Z0-9-_]{0,}$

De no cumplir con el formato especificado, se regresará una excepción de tipo:  InvalidParameterFormat.

String

Mostrar los detalles de una transacción

Implementa la siguiente función para mostrar los detalles de una transacción en específico:

ClipHistory.detail(receiptNumber: ReceiptNumber, object : ClipListener<ClipTransaction?> {
     override fun onCompleteListener(response: ClipTransaction?, error: StatusCode.ClipError?) {}
})

ClipHistory.detail(ReceiptNumber receiptNumber, new ClipListener<ClipTransaction?>() {
            @Override
            public void onCompleteListener(@Nullable ClipTransaction clipTransaction, @Nullable StatusCode.ClipError error) {
            }
        });

La siguiente tabla incluye una descripción para los parámetros de la función:

Elemento

Descripción

receiptNumber

Realiza la búsqueda por el número de recibo que identifica al pago

timeZone

Representación de la zona horaria.

Realizar una devolución de transacción

Implementa la siguiente función para realizar una devolución de transacción en específico:

ClipRefund.refund(receiptNumber: ReceiptNumber, object : ClipListener<Boolean> {
                override fun onCompleteListener(response: Boolean, error: StatusCode.ClipError?) {}})

ClipRefund.refund(ReceiptNumber receiptNumber, new ClipHistoryListener<Boolean>() {
            @Override
            public void onCompleteListener(boolean response, @Nullable StatusCode.ClipError error) {
            }
        }});

La siguiente tabla incluye una descripción para los parámetros de la función:

Elemento

Descripción

receiptNumber

Número de recibo que identifica la transacción a realizar el reembolso

Configurar los ajustes del dispositivo

La librería de Clip permite configurar ciertos ajustes del dispositivo desde tu aplicación de Android.

Actualmente, los ajustes de configuración que se pueden consultar son:

  • Batería: muestra el nivel de batería en el dispositivo Clip.
  • Firmware: muestra la versión de firmware instalada en el dispositivo Clip.
  • Tiempo de apagado: permite configurar el tiempo de apagado automático en tu Clip Plus 2 para ahorrar batería.
  • Sesión de Clip: la sección de ajustes permite cerrar sesión en la cuenta Clip.
  • Lector conectado: permite conectar o desconectar un lector Clip por medio de conexión Bluetooth.

📘

Nota

La configuración de Tiempo de apagado solo está disponible para el dispositivo Clip Plus 2.

Para agregar la función de configuración de ajustes, en el listener del botón tu aplicación Android, agrega la siguiente función:

ClipApi.showSettingsActivity(activity: Activity, loginEnabled: Boolean, logoutEnabled: Boolean, requestCode: Integer)

ClipApi.showSettingsActivity(Activity activity, boolean loginEnabled, boolean logoutEnabled, requestCode: Integer);

La siguiente tabla incluye una descripción para los parámetros de la función:

Elemento

Tipo de Dato

Descripción

loginEnabled

Boolean

Permite mostrar un botón de Login dentro de la pantalla de ajustes.

logoutEnabled

Boolean

Permite mostrar un botón de Logout dentro de la pantalla de ajustes.

Pagos a distancia

El SDK de Clip permite que con tu propia aplicación de Android generes enlaces para pagos a distancia.

Esta sección incluye cómo implementar las siguientes funciones:

  • Crear un enlace para pago a distancia
  • Consultar el historial y realizar búsquedas
  • Consultar detalles individuales de un pago a distancia
  • Cancelar un enlace de pago a distancia

Crear un pago a distancia

Para poder generar un URL de pago a distancia, es necesario llamar a la siguiente función:

ClipApi.launchRemotePaymentActivity(activity: Activity, amount: BigDecimal, requestCode: Int)

ClipApi.launchRemotePaymentActivity(Activity activity, BigDecimal amount, int requestCode);

📘

Nota:

Esta función valida que el formato de la cantidad sea de máximo 5 cifras y 2 decimales. Cualquier cantidad mayor a 99999.99 regresa un código de error 12005.

👍

Mira cómo hacerlo

Consulta la receta con los pasos necesarios para crear un enlace de pago a distancia en tu proyecto.

Consultar el historial de pagos a distancia

Para agregar la función de historial de pagos a tu aplicación, el primer paso es crear un objeto con el tipo de filtro que se desea aplicar.

Los diferentes tipos de búsqueda que incluye este método son:

  • Fecha
  • Rango de fechas
  • Cantidad
  • Correo electrónico del cliente
  • Código de enlace de pago

Para buscar por cantidad del enlace de pago: 

val query = SearchParamsRequest.byAmount(amount: String, page: Int)

Map<String, String> query = SearchParamsRequest.byAmount(String amount, int page);

Para buscar por dirección de correo electrónico del cliente: 

val query = SearchParamsRequest.byCustomerEmail(customerEmail: String, page: Int)

Map<String, String> query = SearchParamsRequest.byCustomerEmail(String customerEmail, int page);

Para buscar por fecha:

val query = SearchParamsRequest.byDate(date: Calendar, page: Int)

Map<String, String> query = SearchParamsRequest.byDate(Calendar date, int page);

Para buscar por rango de fechas:

val query = SearchParamsRequest.byDateRange(dateFrom: Calendar, dateTo: Calendar, page: Int)

Map<String, String> query = SearchParamsRequest.byDateRange(Calendar dateFrom, Calendar dateTo, int page);

Para buscar por código del enlace de pago:

val query = SearchParamsRequest.byRequestNumber(requestCode: String, page: Int)

Map<String, String> query = SearchParamsRequest.byRequestNumber(String requestCode, int page);

Implementar el método de búsqueda:

Después de crear el método con el tipo o tipos de búsqueda a integrar en tu aplicación, agrega el método de búsqueda general.

Para agregar la función de historial de pagos a tu aplicación, implementa el siguiente método:

ClipRemotePayment.search(searchQuery: SearchQuery, object : ClipListener<RemotePaymentHistoryResponse?> {
    override fun onCompleteListener(response: RemotePaymentHistoryResponse?, error: StatusCode.ClipError?) {

    }

    })

ClipRemotePayment.search(Map<String, String> searchQuery, new ClipListener<RemotePaymentHistoryResponse?>() {
    @Override
    public void onCompleteListener(@Nullable RemotePaymentHistoryResponse response, StatusCode.ClipError error) {

    }
});

Filtrar el historial de pagos a distancia por estado de la transacción:

Adicionalmente, la lista de resultados del historial de pagos a distancia permite filtrar por estado de la transacción.

Los estados de transacción que puede tener un pago a distancia son:

  • PENDING: estado pendiente de la transacción desde el momento de su creación hasta que se realiza el pago. Una transacción con estado pendiente tiene un tiempo de expiración de 72 horas.
  • PAID: el pago a distancia ha sido completado de forma exitosa.
  • CANCELLED: el pago a distancia fue cancelado antes de realizar el pago.
  • OVERDUE: el pago no se completó dentro de las 72 horas de validez.
  • REFUNDED: el pago fue reembolsado.

Para integrar el filtro por estado de transacción, crea el siguiente objeto:

val query = SearchParamsRequest.byStatus(status: RemotePaymentFilter, page: Int)

Map<String, String> query = SearchParamsRequest.byStatus(RemotePaymentFilter status, int page);

Los códigos de estado que actúan como parámetro son:

  • RemotePaymentFilter.PENDING: 0
  • RemotePaymentFilter.PAID: 1
  • RemotePaymentFilter.CANCELLED: 2
  • RemotePaymentFilter.OVERDUE: 3
  • RemotePaymentFilter.REFUNDED: 4

La siguiente tabla describe los elementos que regresa la función en el objeto de respuesta RemotePaymentHistoryResponse:

Elemento

Descripción

Tipo de dato

RemotePaymentHistoryResponse

Objeto que contiene los resultados de la consulta del historial

  • Lista del historial
  • Elemento de paginación

object

RemotePaymentItem

Lista de objetos tipo RemotePaymentItem con información del historial de enlaces de pago a distancia.

list

requestId

Identificador para la solicitud del enlace de pago.

string

requestCode

Identificador para el pago, parámetro del enlace URL que se envía al cliente.

string

amount

Cantidad a pagar.

El límite actual para pagos a distancia es de 1500 pesos.

big decimal

customerEmail

Correo electrónico del cliente

string

status

Objeto que mapea el estado correspondiente del enlace de pago

object

RemotePaymentHistoryStatus

Estado del enlace de pago al momento de la consulta.

Posibles estados:

  • PENDING: 0
  • PAID: 1
  • CANCELLED: 2
  • OVERDUE: 3
  • REFUNDED: 4

string

createdDate

Fecha de creación del enlace para pago a distancia

date

dueDate

Fecha de expiración del enlace

date

RemotePaymentPagination

Objeto de paginación para los resultados

totalItems

Número total de elementos que contiene la lista.

integer

itemsPerPage

Especifica el número de elementos a mostrar en cada página.

integer

Consultar los detalles de un pago a distancia

Se consultan los detalles de una transacción por medio del identificador Request Code.

Para consultar los detalles de la transacción, agrega la siguiente función:

ClipRemotePayment.detail(requestCode: String, object : ClipListener<RemotePaymentDetailResponse?>{
    override fun onCompleteListener(response: RemotePaymentDetailResponse, error: StatusCode.ClipError?) {

    }

})

ClipRemotePayment.detail(String requestCode, new ClipListener<RemotePaymentDetailResponse>(){
    @Override
    public void onSuccess(@Nullable RemotePaymentDetailResponse response, @Nullable StatusCode.ClipError error) {

    }

});

La siguiente tabla describe los elementos que regresa la función en el objeto de respuesta RemotePaymentDetailResponse:

Elemento

Descripción

Tipo de dato

RemotePaymentDetailResponse

Objeto que contiene los detalles de un pago a distancia

object

requestId

Identificador para la solicitud del enlace de pago.

string

requestCode

Identificador para el pago, parámetro del enlace URL que se envía al cliente.

string

amount

Cantidad a pagar.

El límite actual para pagos a distancia es de 1500 pesos.

big decimal

customerEmail

Correo electrónico del cliente.

string

status

Objeto que contiene información del estado del enlace de la transacción.

object

RemotePaymentHistoryStatus

Posibles estados:

  • PENDING: 0
  • PAID: 1
  • CANCELLED: 2
  • OVERDUE: 3
  • REFUNDED: 4

createdDate

Fecha de creación del enlace para pago a distancia.

date

dueDate

Fecha de expiración del enlace de pago.

date

message

Concepto personalizado al crear el enlace.

string

closedDate

Fecha en que se finalizó el proceso de transacción.

date

link

Enlace para el pago a distancia que contiene como parámetro el requestCode.

string

receiptNumber

Número de recibo proporcionado por el cliente.

string

cardLast4

Últimos 4 dígitos del número de tarjeta utilizada para el pago.

string

Cancelar un pago a distancia

La librería del SDK de Clip permite cancelar un URL de pago a distancia antes de que se haya completado el pago.

La solicitud de un pago a distancia se identifica por un Request Code.

Para cancelar un pago a distancia, agrega la siguiente función:

ClipRemotePayment.cancel(requestCode: RequestCode, object : ClipListener<RemotePaymentDetailResponse?>{
    override fun onCompleteListener(response: RemotePaymentDetailResponse?, error: StatusCode.ClipError?) {
        
    }

})

ClipRemotePayment.cancel(RequestCode requestCode, new ClipListener<RemotePaymentDetailResponse>() {
    @Override
    public void onCompleteListener(@Nullable RemotePaymentDetailResponse response, @Nullable StatusCode.ClipError error) {
        
    }

});