Tratar Respostas e Erros

O Get Smart SDK (redsys-tpv-business-lib) utiliza uma abordagem unificada para lidar com os resultados de operações assíncronas. Cada função de repositório é uma função suspend que retorna um wrapper RepositoryResult<T>.

Este wrapper serve a dois propósitos principais:

1. Segurança: Força você a tratar explicitamente os casos de falha, evitando que exceções não tratadas causem o fechamento (crash) do seu app.
2. Consistência: Fornece uma estrutura padrão para sucesso, erros de rede, cancelamentos de usuário e problemas de protocolo em todos os recursos (Pagamentos, Estornos, Inicialização, etc.).

A Estrutura do RepositoryResult

O RepositoryResult<T> é uma sealed class (classe selada) do Kotlin. Isso significa que, ao consumir um resultado usando uma expressão when, o compilador garantirá que você trate todos os desfechos possíveis (ou use um ramo else).

Tipos de Resultado

Ao chamar uma função como paymentRepository.makePayment(...), o resultado será um dos seguintes:

1. Sucesso (Success<T>)

A operação foi concluída com êxito e o SDK recebeu uma resposta válida do Get Smart SDK Payment Service.

• Propriedades: Contém uma propriedade data do tipo T.
• Uso: Acesse result.data para obter o payload real (ex: PaymentResult, TpvInfo, Transaction).

2. Erro de Conexão (ConnectionError)

A comunicação com o serviço ou com o Host falhou.

• Causa: Geralmente indica um problema de rede ou que o Get Smart SDK Payment Service não está rodando/instalado no dispositivo.
• Propriedades: Este objeto não possui propriedades extras (data object).
• Ação: Solicite ao usuário que verifique a conexão com a internet ou tente a operação novamente.

3. Cancelado (Cancelled)

A operação foi cancelada manualmente pelo usuário ou pelo sistema.

• Causa: O usuário pressionou o botão “Cancelar” na tela do TPV durante um pagamento ou outro fluxo interativo.
• Propriedades: Contém uma string message explicando o motivo do cancelamento.
• Ação: Informe ao usuário que o processo foi interrompido.

4. Erro de Protocolo (ProtocolError)

Representa um erro de integração ou lógico que impede a execução da operação.

• Propriedades:
  • type: Um enum ProtocolErrorType indicando a categoria do erro.
  • description: Uma string opcional com mais detalhes.

Referência de ProtocolErrorType

O enum ProtocolErrorType ajuda você a diagnosticar problemas de integração programaticamente:

Exemplo de Implementação

Aqui está um padrão prático para tratar resultados em sua camada de ViewModel ou UseCase. Note a verificação aninhada para PaymentResult dentro do bloco de sucesso.

import es.redsys.adquirencia.tpva.service.model.RepositoryResult
import es.redsys.adquirencia.tpva.service.model.ProtocolErrorType

suspend fun processPayment(amount: Money) {
    // 1. Call the repository
    val result = paymentRepository.makePayment(amount)

    // 2. Handle all possible outcomes
    when (result) {
        is RepositoryResult.Success -> {
            // Operation succeeded, business logic continues here
            // Note: For payments, you still need to check the business result (Accepted/Denied) inside 'data'
            val paymentOutcome = result.data
            handlePaymentOutcome(paymentOutcome)
        }

        is RepositoryResult.ConnectionError -> {
            // Infrastructure failure
            viewState.showError("Connection failed. Please check internet and try again.")
        }

        is RepositoryResult.Cancelled -> {
            // User abort
            viewState.showInfo("Operation cancelled: ${result.message}")
        }

        is RepositoryResult.ProtocolError -> {
            // Developer/Integration error
            if (result.type == ProtocolErrorType.TPV_NOT_INITIALIZED) {
                viewState.showError("Critical: TPV not initialized.")
                // Trigger re-initialization logic
            } else {
                viewState.showError("Integration Error: ${result.description}")
            }
        }
    }
}

Próximos Passos

Agora que você entende o wrapper de resultado genérico, está pronto para implementar recursos específicos:

• Inicializar o TPV: O primeiro passo obrigatório para qualquer integração.
• Criar um Pagamento Pré-autorizado: Aprenda como processar uma transação de pré-autorização.
• Criar um Pagamento de Etapa Única: Aprenda como realizar pagamentos de etapa única.
• Criar um Pagamento com Parcelamento (Plazox): Aprenda como realizar pagamentos parcelados.