6 - Cancelamento

Cancele transações no terminal SmartPOS informando um transactionId específico ou selecionando uma transação listada no terminal.

Mesmo quando você informa um transactionId, a leitura do cartão ainda é necessária durante o cancelamento.

Pré-requisitos

Antes de iniciar um cancelamento:

1. Ative o terminal em Ativação SmartPOS.

2. Inicialize o SDK e plugue o SmartPOSPlugin em Inicialização SmartPOS.

3. Tenha o transactionId da transação, se for cancelar uma transação específica.

4. Prepare a interface para exibir mensagens, menus e lista de transações canceláveis.

5. Solicite as permissões Android necessárias em tempo de execução.

Classe utilizada

Para cancelamentos, use a classe SmartPOSVoidRequestBuilder.

A requisição é criada por:

SmartPOSPlugin.createVoidRequestBuilder()

Modos de cancelamento

Você pode cancelar de duas formas:

Modo	Como funciona	Parâmetros principais
Cancelamento por transação específica	Informe o `transactionId` da transação que será cancelada.	`transactionId`
Cancelamento por listagem	Omita `transactionId` para listar transações no terminal e permitir seleção.	`option`

Se transactionId for omitido, nulo ou vazio, o fluxo segue para listagem de transações. Nesse caso, option se torna obrigatório.

Exemplo

val voidRequest = SmartPOSPlugin.createVoidRequestBuilder()
    .transactionId("")
    .option(Option.CREDIT)
    .callback(object: Callback<SmartPOSVoidResponse>() \{
        override fun onStart() {
            startLoadingAnimation()
        }

        override fun onSuccess(response: SmartPOSVoidResponse) {
            handleSucessfullVoid(response)
        }

        override fun onFail(exception: Throwable) {
            handleVoidFailure(exception)
        }

        override fun onComplete() {
            stopLoadingAnimation()
        }
    \})
    .voidTransactionCallback(object: Callback<UserSelection<VoidTransaction>>() \{
        override fun onSuccess(response: UserSelection<VoidTransaction>) {
            assembleList(response)
        }

        override fun onFail(exception: Throwable) {
        }
    \})
    .messageCallback(object: Callback<MessageCallbackRequestField.MessageData>() \{
        override fun onSuccess(messageData: MessageCallbackRequestField.MessageData) {
            displayMessage()
        }

        override fun onFail(throwable: Throwable) {
        }
    \})
    .menuSelectionCallback(object: Callback<SmartPOSMenuOptions>() \{
        override fun onSuccess(response: SmartPOSMenuOptions) {
            assembleOptionsList(response.options.iterable)
        }

        override fun onFail(error: Throwable) {
        }
    \})
    .build()

Zoop.post(voidRequest)

Parâmetros

`.transactionId`

Informe transactionId para cancelar uma transação específica.

.transactionId("{transactionId}")

Se transactionId for omitido, null ou vazio, o plugin inicia o fluxo de listagem de transações. Ainda assim, a leitura do cartão será necessária.

`.option`

Informe a opção de pagamento da transação que deseja cancelar.

.option(Option.CREDIT)

Se transactionId for informado, option pode ser omitido. Se transactionId não for informado, option é obrigatório.

Opções de pagamento

Option.CREDIT // Crédito à vista ou parcelado
Option.DEBIT  // Débito

Callbacks

`.callback`

Controla o fluxo principal do cancelamento: início, sucesso, falha e conclusão.

Método	Quando ocorre	Ação recomendada
`onStart`	O fluxo de cancelamento começou.	Inicie um loading ou bloqueie ações concorrentes.
`onSuccess`	A transação foi cancelada.	Use `response.transactionData` para salvar o cancelamento ou imprimir recibo.
`onFail`	O cancelamento falhou.	Trate a exceção e exiba uma mensagem para o operador.
`onComplete`	O fluxo terminou, com sucesso ou falha.	Remova loading e libere a interface.

Retorno de sucesso

Em onSuccess, você recebe um objeto SmartPOSVoidResponse contendo TransactionData.

Para imprimir o recibo, envie esse objeto para o request de impressão.

data class TransactionData(
    val value: Int?, // Valor da transação em centavos
    val paymentType: Int?, // Tipo de pagamento
    val installments: Int?, // Parcelas
    val status: String?, // Status (approved/canceled)
    val brand: String?, // Marca do cartão ex: Visa
    val address: String?, // Endereço do seller
    val sellerName: String?, // Nome do seller
    val acquiring: String?, // Adquirente
    val pan: String?, // PAN do cartão
    val autoCode: String?, // Código de autorização
    val documentType: String?, // Tipo de documento, CPF/CNPJ
    val document: String?, // Documento
    val nsu: String?, // NSU
    val date: String?, // Data da transação
    val hour: String?, // Hora da transação
    val cv: String?, // CV
    val arqc: String?, // ARQC
    val aid: String?, // AID
    val sellerReceipt: String?, // Recibo do estabelecimento
    val customerReceipt: String?, // Recibo do cliente
    val approvalMessage: String?, // Mensagem de aprovação ex: APROVADA PELO EMISSOR,
    val aidLabel: String?, // Label do cartão
    var transactionId: String?, // Id da transação
    val receiptId: String? = null, // Id do recibo, caso aplicável (hoje, apenas transações Pix)
    val pixId: String? = null, // Id do Pix
    val cardFingerprint: String? = null // Token único do cartão.
)

Exceções de falha

Em onFail, você pode receber uma destas exceções:

Exceção	Quando ocorre
`ZoopPaymentException`	Falha no fluxo do cancelamento. A mensagem pode ser acessada em `exception.message`.
`ZoopTimeoutException`	Tempo excedido na operação.
`ZoopClosedConnectionException`	Conexão interrompida.
`ZoopNetworkException`	Falha de conexão.

`.messageCallback`

Recebe mensagens do fluxo de cancelamento, como instruções para aproximação, inserção ou passagem do cartão.

Método	Quando ocorre	Ação recomendada
`onSuccess`	Uma mensagem foi enviada pelo fluxo.	Exiba `response.message` ou `messageData.message` para o usuário.
`onFail`	Não recebe dados.	Nenhuma ação necessária.

`.menuSelectionCallback`

Solicita que o app exiba uma seleção manual de aplicação do cartão.

A aplicação deve exibir a lista com as opções recebidas e permitir que uma opção seja selecionada em até 30 segundos. Se nenhuma opção for selecionada, a operação será cancelada.

Para selecionar uma opção, use:

response.options.select(MenuOptionsData)

Retorno

data class SmartPOSMenuOptions(
    val options: List<MenuOptionsData>, // Lista de itens, acessada como response.options.iterable
    val title: String, // Título do tipo de seleção requisitada. Ex: "Opções do cartão"
    val defaultOption: Int // Opção padrão pré-definida.
)

data class MenuOptionsData(
    val index: Int, // Valor a ser exibido como índice do item na lista.
    val itemName: String // Título do item do menu. Ex: "Crédito"
)

Método	Quando ocorre	Ação recomendada
`onSuccess`	Há opções para seleção manual.	Exiba a lista e chame `select()` com a opção escolhida.
`onFail`	Não recebe dados.	Nenhuma ação necessária.

`.voidTransactionCallback`

Solicita que o app exiba uma lista de transações para o usuário selecionar qual será cancelada.

A aplicação deve permitir a seleção de uma transação em até 30 segundos. Se o tempo expirar, a operação será cancelada e a mensagem será enviada pela messageCallback.

Use a propriedade items do objeto UserSelection<VoidTransaction> para obter a lista. Para selecionar a transação, chame o método select() no objeto recebido.

Retorno

data class VoidTransaction(
    val id: String,
    val amount: String,
    val option: Option,
    val cardBrand: CardBrand,
    val date: String,
    val time: String
)

Método	Quando ocorre	Ação recomendada
`onSuccess`	A lista de transações foi retornada.	Exiba as transações e chame `select()` com a transação escolhida.
`onFail`	Não recebe dados.	Nenhuma ação necessária.

Checklist de cancelamento

Antes de enviar a requisição com Zoop.post(voidRequest), confirme:

O SDK foi inicializado com credenciais.
O SmartPOSPlugin foi plugado.
O app sabe se cancelará por transactionId ou por listagem.
Se transactionId estiver vazio, option foi informado.
A interface exibe mensagens do messageCallback.
A interface trata seleção manual de aplicação do cartão.
A interface trata lista de transações quando voidTransactionCallback for chamado.
O app permite selecionar uma opção ou transação em até 30 segundos.
O app trata sucesso, falha e conclusão no .callback.

Próximo passo

Depois de implementar cancelamento, consulte Impressão SmartPOS para imprimir vias de cancelamento ou reimpressões.