CONNECTTEF – INTEGRAÇÃO VIA INTENT ANDROID (ESTORNO).

Resumo do que será ensinado

Neste documento você vai aprender como realizar estorno (cancelamento) de uma transação de pagamento em um SmartPOS usando a integração via Intent Android com o ConnectTEF. Serão detalhados: como montar o Intent de estorno, quais parâmetros obrigatórios precisam ser enviados, como validar a resposta no onActivityResult e quais campos retornados devem ser armazenados para controle financeiro e auditoria. 

Segue um Vídeo explicativo do processo

Detalhamento do uso correto

Com este guia, um desenvolvedor Android iniciante será capaz de configurar o app para solicitar estorno de uma venda já realizada pelo ConnectTEF, tratar corretamente o retorno (sucesso ou falha) e registrar o estorno no sistema, mantendo vínculo com a transação original e garantindo rastreabilidade. 

Segue o detalhamento de como realizar Estorno via Intent Android com o ConnectTEF

1. Entender o objetivo do Estorno via Intent

   • O estorno via Intent Android serve para reverter uma transação de pagamento previamente autorizada, usando o mesmo SmartPOS e o app ConnectTEF. 
     Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
   • Em resumo:
     • Seu app monta um Intent de estorno com os dados da transação original.
     • Envia esse Intent ao aplicativo ConnectTEF instalado no POS.
     • O ConnectTEF executa o estorno junto à adquirente.
     • O resultado (aprovado ou não) retorna ao seu app via Intent (por exemplo, no onActivityResult). 
       Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade

   Ponto importante

   • O estorno depende da transação original: é obrigatório informar o número da transação e a finalização obtidos quando o pagamento foi realizado. 
     Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
     .

2. Exemplo de chamada de Estorno via Intent

   A documentação apresenta um exemplo de método para realizar estorno usando um adaptador: 

   Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade

   public class ConnectTEFAdapter {

       public void realizarEstorno(Activity activity, int requestCode) {
           Intent intent = new Intent();
           intent.setComponent(new ComponentName(
                   "br.com.pdvpos.connecttef.gerenciador",
                   "br.com.pdvpos.connecttef.gerenciador.MainActivity"));

           if (intent.resolveActivity(activity.getPackageManager()) != null) {
               intent.putExtra("identificacao", "abc123");
               intent.putExtra("valorTotal", 29.90);
               intent.putExtra("tipoTransacao", "10");
               intent.putExtra("numeroTransacao", "abc123");
               intent.putExtra("finalizacao", "abc123|abc123|zbc123");

               activity.startActivityForResult(intent, requestCode);
           } else {
               Toast.makeText(activity,
                       "Aplicativo externo não encontrado.",
                       Toast.LENGTH_SHORT).show();
           }
       }
   }

Pontos de atenção

• O ComponentName deve apontar para o aplicativo ConnectTEF instalado no SmartPOS (br.com.pdvpos.connecttef.gerenciador). 
  Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
• O app ConnectTEF precisa estar instalado; caso contrário, o Intent não será resolvido e o estorno não será executado.

1. Parâmetros enviados no Intent (bundle de estorno)

   De acordo com a documentação, o bundle do Intent de estorno contém os seguintes campos principais: 

   Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade

   • Parâmetros de envio (extras obrigatórios e opcionais)

     Campo	Tipo	Obrigatório	Descrição
     identificacao	string	Sim	ID único da transação no seu sistema. Ajuda a relacionar o estorno à venda.
     valorTotal	decimal	Sim	Valor total da venda que está sendo estornada. Ex.: 29.9 para R$ 29,90.
     tipoTransacao	string	Sim	Código da transação (tipo de operação) conforme tabela de transações.
     quantidadeParcelas	string	Não	Nº de parcelas da venda original (se aplicável). Ex.: "1".
     imprimirComprovante	bool	Não	Indica se o POS deve imprimir o comprovante de estorno.
     numeroTransacao	string	Sim	Número único da transação fornecido pela adquirente na venda original.
     finalizacao	string	Sim	Dados técnicos de finalização obtidos na resposta do pagamento original.

   Pontos de atenção

   • numeroTransacao e finalizacao são críticos: sem eles, o ConnectTEF não consegue localizar e estornar a transação original junto à adquirente. 
     Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
   • valorTotal deve ser coerente com o valor da venda original (normalmente o mesmo valor).

2. Como validar a resposta do Estorno (onActivityResult)

   A documentação recomenda um padrão de tratamento da resposta no método de callback: 

   Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade

   public class MainActivity extends AppCompatActivity {

       private static final String TAG = "ConnectTEF";

       @Override
       protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
           super.onActivityResult(requestCode, resultCode, data);

           if (data == null) {
               Log.w(TAG, "Operação cancelada");
               return;
           }

           Bundle bundle = data.getExtras();
           if (bundle == null) {
               Log.w(TAG, "Operação cancelada");
               return;
           }

           if (resultCode != RESULT_OK) {
               String mensagemErro = bundle.getString("textoEspecialOperador");
               if (mensagemErro != null) {
                   Log.w(TAG, "Mensagem de erro: " + mensagemErro);
               } else {
                   Log.w(TAG, "Erro na operação, mas sem mensagem específica.");
               }
               return;
           }

           for (String key : bundle.keySet()) {
               Object value = bundle.get(key);
               Log.d(TAG, key + " => " + value);
           }
       }
   }

Pontos de atenção

• Se data ou bundle forem nulos, considere que a operação foi cancelada ou não chegou a ser concluída. 
  Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
• Quando resultCode != RESULT_OK, use textoEspecialOperador para obter uma mensagem amigável de erro ou cancelamento e exibir ao usuário.
• Em ambiente de desenvolvimento, iterar sobre bundle.keySet() ajuda a conhecer todos os campos retornados pela operação de estorno.

1. Parâmetros da resposta (bundle retornado pelo ConnectTEF)

   O Intent de resposta do estorno traz diversos campos com informações sobre a operação: 

   Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade

   • Principais campos da resposta

     Campo	Tipo	Descrição
     identificacao	string	Identificador único da operação (mesmo enviado na requisição).
     valorTotal	string	Valor total da transação estornada.
     statusTransacao	string	"0" = sucesso; outros valores indicam falha/cancelamento.
     nomeRede	string	Nome da adquirente (rede) responsável pela transação.
     tipoTransacao	string	Tipo da transação (de acordo com tabela de tipos).
     numeroTransacao	string	Número sequencial da transação de estorno.
     codigoAutorizacaoTransacao	string	Código de autorização do estorno fornecido pela adquirente.
     quantidadeParcelas	string	Número de parcelas associadas à transação (quando aplicável).
     dataTransacaoComprovante	string	Data da transação no comprovante (formato ddMMyyyy).
     horaTransacaoComprovante	string	Hora da transação no comprovante (formato hhmmss).
     numeroTransacaoCancelada	string	Número da transação original que foi cancelada (venda estornada).
     timestampTransacaoCancelada	string	Timestamp da transação original (formato ddMMhhmmss).
     finalizacao	string	Dados técnicos da finalização da transação de estorno.
     quantidadeLinhasComprovante	string	Quantidade de linhas do comprovante impresso.
     textoEspecialOperador	string	Mensagem especial para exibição ao operador (erro, alerta, instrução).
     numeroSerieTerminal	string	Número de série do terminal (SmartPOS).
     executada	boolean	Indica se a operação foi processada (true) ou não.
     cnpj	string	CNPJ do estabelecimento.
     bandeiraCartao	string	Bandeira do cartão usado na transação original (ex.: MASTERCARD).

   Pontos de atenção

   • Campo chave para sucesso:
     
     • statusTransacao == "0" → estorno aprovado.
     • Outro valor → estorno não realizado; use textoEspecialOperador para entender o motivo. 
       Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
   • numeroTransacaoCancelada é essencial para relacionar o estorno com a venda original em seu banco de dados.

2. Fluxo recomendado dentro do seu app Android

   1. Guardar dados da venda original

      • Ao realizar o pagamento via Intent, salve:
      • numeroTransacao.
      • finalizacao.
      • identificacao.
      • valorTotal.

   2. Montar o Intent de estorno

      • Use esses dados para preencher:
      • identificacao (pode ser o mesmo ID da venda ou um novo ID para o estorno, desde que você vincule internamente).
      • valorTotal.
      • tipoTransacao (código adequado para estorno).
      • numeroTransacao (da venda original).
      • finalizacao (da venda original).
      • imprimirComprovante (conforme regra de negócio).

   3. Enviar o Intent e aguardar retorno

      • Chame startActivityForResult(intent, requestCode).
      • Trate o retorno em onActivityResult, seguindo o padrão da documentação. 
        Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade

   4. Interpretar o resultado

      • Se resultCode != RESULT_OK:
      • Considere o estorno não concluído e use textoEspecialOperador para informar o operador.
      • Se resultCode == RESULT_OK:
      • Leia statusTransacao.
      • Se statusTransacao == "0":
        
        • Marque o estorno como aprovado.
        • Registre numeroTransacao, codigoAutorizacaoTransacao, numeroTransacaoCancelada, valorTotal, bandeiraCartao, nomeRede.
      • Caso contrário:
        
        • Registre o estorno como falho e exiba mensagem apropriada.

   5. Atualizar o sistema interno

      • Atualize relatórios, recibos e lançamentos financeiros:
      • Venda original → marcada como estornada.
      • Estorno → registrado com referência à transação original (numeroTransacaoCancelada).

   Ponto importante

   • Nunca considere uma venda como estornada sem antes validar resultCode e statusTransacao, garantindo que o estorno foi realmente aprovado pela adquirente. 
     Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
     .

3. Boas práticas de implementação

   • Persistência e vínculo:
     • Mantenha tabelas/estruturas que relacionem cada estorno ao NSU da transação original (numeroTransacaoCancelada).
   • Auditoria:
     • Guarde finalizacao, codigoAutorizacaoTransacao, dataTransacaoComprovante e horaTransacaoComprovante para verificar eventuais divergências com a adquirente.
   • Interface com o operador:
     • Use textoEspecialOperador para exibir mensagens claras: estorno aprovado, recusado, prazo expirado etc.
   • Logs:
     • Em ambiente de testes, registre todos os campos retornados (for (String key : bundle.keySet() ...)) para compreender o comportamento completo.

Informações Importantes

• Função da integração via Intent – Estorno: permitir que um app Android reverta transações de pagamento realizadas em SmartPOS usando o ConnectTEF, sem implementar diretamente APIs HTTP ou Webhooks. 
  Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
• Campos essenciais de envio:
  • identificacao, valorTotal, tipoTransacao, numeroTransacao, finalizacao, imprimirComprovante (opcional). 
    Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
• Campos essenciais de resposta:
  • statusTransacao, numeroTransacao, codigoAutorizacaoTransacao, numeroTransacaoCancelada, valorTotal, nomeRede, bandeiraCartao, textoEspecialOperador. 
    Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade
• Critério de sucesso:
  • resultCode == RESULT_OK e statusTransacao == "0" → estorno aprovado.
• Benefícios de seguir corretamente o procedimento:
  • Estornos integrados de forma segura, rastreável e alinhada com o fluxo de pagamento via Intent.
  • Facilita conciliação financeira e suporte, pois os dados técnicos da transação e do estorno ficam disponíveis.
• Recomendações gerais:
  • Use este guia na sua base de conhecimento interna para treinar desenvolvedores Android.
  • Sempre implemente Pagamento via Intent antes do estorno, pois o estorno depende dos dados da transação original.
  • Teste o fluxo completo (venda + estorno) em ambiente de homologação antes de levar para produção. 
    Estorno | Conecte seu sistema a múltiplas adquirentes com facilidade

Este texto está pronto para ser copiado em um documento Word da sua base de conhecimento. Basta aplicar o padrão visual: título com fonte 34, cabeçalhos (Resumo, Vídeo, Detalhamento, Informações Importantes) com fonte 18, e o corpo em fonte menor, mantendo os pontos críticos em negrito conforme necessário.