7 - Cancelamento

Fluxos de cancelamento

O SDK permite cancelar uma transação de duas formas:

Informe transactionId para cancelar uma transação específica.
Omita transactionId, envie null ou uma string vazia para listar as transações disponíveis e permitir que o usuário selecione uma.

Quando o fluxo de listagem for usado, exiba as transações recebidas em voidTransactionCallback para que o usuário selecione qual transação será cancelada. Após a seleção, o SDK executa o cancelamento e notifica o andamento pela messageCallback.

✅
Use response.select(transaction) no objeto UserSelection<VoidTransaction> recebido em voidTransactionCallback para selecionar a transação que será cancelada.
O usuário tem até 30 segundos para selecionar uma transação. Após esse prazo, a operação é cancelada.

Criar um cancelamento

Para criar e executar uma solicitação de cancelamento:

1. Crie a requisição com MPOSPlugin.createVoidRequestBuilder().
2. Informe .transactionId() se quiser cancelar uma transação específica.
3. Configure .callback() para acompanhar início, sucesso, falha e conclusão.
4. Configure .voidTransactionCallback() para tratar a seleção de transação quando transactionId não for informado.
5. Configure .messageCallback() para exibir mensagens do SDK.
6. Execute a requisição com Zoop.post(voidRequest).

Exemplo

val voidRequest = MPOSPlugin.createVoidRequestBuilder()
    .transactionId("")
    .callback(object: Callback<mPOSVoidResponse>() {
        override fun onStart() {
            state = state.copy(status = Status.MESSAGE, message = "Processando")
        }

        override fun onSuccess(response: mPOSVoidResponse) {
            state = state.copy(status = Status.MESSAGE, message = "Cancelamento realizado")
            voidTransaction = null
        }

        override fun onFail(error: Throwable) {
            state = state.copy(
                status = Status.MESSAGE,
                message = error.message ?: "Falha na operação"
            )
            voidTransaction = null
        }

        override fun onComplete() {
            state = state.copy(status = Status.FINISHED, message = "")
        }
    })
    .voidTransactionCallback(object: Callback<UserSelection<VoidTransaction>>() {
        override fun onSuccess(response: UserSelection<VoidTransaction>) {
            voidTransaction = response
            state = state.copy(
                transactionsList = voidTransaction!!.items.toList(),
                status = Status.DISPLAY_VOID_LIST
            )
        }

        override fun onFail(error: Throwable) {
        }
    })
    .messageCallback(object: Callback<MessageCallbackRequestField.MessageData>() {
        override fun onSuccess(response: MessageCallbackRequestField.MessageData) {
            state = state.copy(status = Status.MESSAGE, message = response.message)
        }

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

Zoop.post(voidRequest)

Parâmetros

.transactionId

Use transactionId para cancelar uma transação específica. Quando esse valor não for informado, for null ou estiver vazio, o SDK inicia o fluxo de listagem de transações.

Ainda assim, a leitura do cartão será necessária.

Parâmetro	Tipo	Obrigatório	Descrição
`transactionId`	String	Não	ID da transação a ser cancelada. Quando omitido, `null` ou vazio, o SDK inicia o fluxo de listagem de transações.

Callbacks

Use os callbacks para acompanhar o ciclo de vida do cancelamento, exibir mensagens na interface e selecionar a transação quando o fluxo de listagem for usado.

.callback

Responsável pelo fluxo do cancelamento, incluindo início, processamento e conclusão com sucesso ou falha.

Callback	Quando é chamado	Uso recomendado
`onStart`	Quando o fluxo do cancelamento começa.	Exibir uma mensagem de carregamento, como `Processando cancelamento`.
`onSuccess`	Quando a transação é cancelada com sucesso.	Ler os dados retornados no `TransactionData` e exibir a confirmação do cancelamento.
`onFail`	Quando ocorre uma falha no cancelamento.	Registrar a exception e exibir uma mensagem de falha para o usuário.
`onComplete`	Quando o fluxo termina, tanto em casos de sucesso quanto de falha.	Finalizar estados de carregamento ou limpar controles temporários da interface.

Resposta de sucesso

Quando o cancelamento é concluído com sucesso, o SDK retorna um TransactionData com os dados da transação cancelada.

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
    val 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
    var cardFingerprint: String? = null, // Token único do cartão
    val cardEntryMode: String? // Identifica qual o modo de entrada do cartão(TARJA, CHIP, NFC)
)

Exceções

Em caso de falha, a aplicação recebe uma exception, que pode ser de um dos seguintes tipos:

ZoopPaymentException: falha no fluxo do pagamento. A mensagem de erro pode ser acessada por exception.message.
ZoopTimeoutException: tempo excedido na operação.
ZoopClosedConnectionException: conexão interrompida.
ZoopNetworkException: falha de conexão.

.voidTransactionCallback

Responsável pela seleção da transação a ser cancelada a partir de uma lista fornecida pelo SDK.

Callback	Quando é chamado	Uso recomendado
`onSuccess`	Quando o SDK retorna a lista de transações disponíveis para cancelamento.	Exibir `response.items` para o usuário e chamar `response.select(transaction)` após a seleção.
`onFail`	Não é chamado nesse callback.	Não implementar ações dependentes de falha neste callback.

A aplicação deve exibir uma lista de transações para que o usuário selecione uma delas em até 30 segundos. Esgotado esse limite de tempo, a operação será cancelada e notificada na messageCallback.

Obtenha a lista de transações pela propriedade items do objeto UserSelection<VoidTransaction> recebido em onSuccess(). Selecione a transação para cancelamento com o método select() desse mesmo objeto.

Modelo de transação para cancelamento

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

.messageCallback

Responsável pelas mensagens exibidas durante o fluxo do cancelamento.

Callback	Quando é chamado	Uso recomendado
`onSuccess`	Quando o SDK envia uma mensagem operacional do cancelamento.	Exibir `response.message` na interface da aplicação.
`onFail`	Não é chamado nesse callback.	Não implementar ações dependentes de falha neste callback.

Cancelar uma operação em andamento

Chame cancel() quando precisar interromper uma operação de cancelamento em andamento. Use o mesmo objeto de requisição passado ao método Zoop.post() ou Zoop.enqueue().

📘
O cancelamento é assíncrono e cooperativo. O método cancel() sinaliza a intenção de cancelamento para o SDK e retorna imediatamente, sem aguardar a conclusão do cancelamento. O SDK interrompe e cancela a operação na primeira oportunidade possível.

Exemplo

var voidRequest: Request? = null

fun voidPayment() {
    voidRequest = MPOSPlugin.createVoidRequestBuilder()
        // ...
        .build()

    Zoop.post(voidRequest)
}

fun cancelVoid() {
    voidRequest?.cancel()
}

Acompanhe o resultado final da operação pelos callbacks configurados na requisição.