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

Resumo do que será ensinado

Neste documento será explicado, passo a passo, como realizar um pagamento em SmartPOS usando a integração via Intent Android com o ConnectTEF. Você vai ver como montar o Intent de chamada, quais campos precisam ser enviados, como validar a resposta no onActivityResult e quais são os campos retornados para registrar corretamente a transação no seu sistema. 

Segue um Vídeo explicativo do processo

Detalhamento do uso correto

Com este guia, qualquer desenvolvedor Android deve ser capaz de configurar o app para disparar pagamentos pelo ConnectTEF via Intent, tratar o retorno (sucesso, cancelamento ou erro) e armazenar os dados essenciais da transação, como valor, status, código de autorização, NSU e bandeira do cartão. 

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

1. Entender o objetivo da integração de Pagamento via Intent

   • A integração via Intent Android permite que o seu aplicativo Android peça ao ConnectTEF no SmartPOS para executar uma transação de pagamento, sem que o app implemente diretamente toda a lógica TEF. 
     Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
   • Seu app:
     • Monta um Intent com os dados da venda.
     • Envia o Intent para o app/serviço do ConnectTEF.
     • Aguarda o resultado no método de callback (onActivityResult, por exemplo). 
       Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade

   Ponto importante

   • O ConnectTEF cuida da interação com o cliente (telas de pagamento, cartão, parcelas). O seu app apenas dispara a operação e consome os dados de retorno para finalizar a venda.

2. Configurar a chamada de Pagamento via Intent

   • A documentação fornece um exemplo de classe adaptadora para realizar o pagamento: 
     Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade

   public class ConnectTEFAdapter {

       public ConnectTEFAdapter() {
       }

       public void realizarPagamento(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("imprimirComprovante", true);
               intent.putExtra("quantidadeParcelas", 1);

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

• Campos enviados no Intent: 

  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  • identificacao: ID único da transação no seu sistema (string).
  • valorTotal: valor total da venda, em decimal (por exemplo, 29.90 para R$ 29,90).
  • tipoTransacao: código da transação (string), conforme tabela de tipos.
  • imprimirComprovante: indica se deve imprimir o comprovante no POS (boolean).
  • quantidadeParcelas: número de parcelas (string ou int, ex.: 1).

  Pontos de atenção

• O ComponentName deve apontar para o aplicativo ConnectTEF instalado no SmartPOS; se não encontrar (resolveActivity == null), é sinal de que o app não está disponível. 

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

• identificacao precisa ser único por transação para facilitar rastreio e conciliação.

1. Tabela de parâmetros do bundle enviado (Intent de pagamento)

   De acordo com a documentação, os principais parâmetros usados no bundle do Intent são: 

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

   • Parâmetros de envio (extras do Intent)

     Campo	Tipo	Obrigatório	Descrição
     identificacao	string	Sim	ID único da transação no seu sistema.
     valorTotal	decimal	Sim	Valor total da venda. Ex.: 29.9 para R$ 29,90.
     tipoTransacao	string	Não	Código da transação (ver tabela de tipos abaixo).
     quantidadeParcelas	string	Não	Número de parcelas. Ex.: "1".
     imprimirComprovante	bool	Não	Indica se o comprovante será impresso no POS.
     numeroTransacao	string	Não	Número único de transação fornecido pela adquirente (NSU).
     finalizacao	string	Não	Dados técnicos da finalização (usado em fluxos avançados).

   Pontos de atenção

   • Para um primeiro uso, foque em identificacao, valorTotal, tipoTransacao, quantidadeParcelas e imprimirComprovante. 
     Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
   • numeroTransacao e finalizacao são mais usados em cenários avançados (estorno, reprocessamento).

2. Tipos de transação (tipoTransacao) disponíveis

   A documentação utiliza códigos numéricos (em string) para representar o tipo de transação: 

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

   Exemplos comuns (a lista completa está na documentação oficial):

   • 10 – Crédito à vista.
   • Outros códigos cobrem crédito parcelado, débito, PIX/carteira digital, voucher/PAT etc.

   Ponto importante

   • Use o código adequado ao tipo de pagamento que seu fluxo exige (por exemplo, crédito parcelado, débito, voucher). Consulte a tabela completa de tipos na documentação para implementar tudo corretamente. 
     Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade

3. Disparar o Intent e aguardar a resposta

   • Após configurar o Intent com os extras, o app chama: 
     Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade

    activity.startActivityForResult(intent, requestCode);
   

   • O Android abrirá o app ConnectTEF (no SmartPOS), que fará a operação de pagamento.
   • Quando o processo terminar (aprovado, cancelado ou erro), o Android retornará ao seu app e chamará o callback de resultado (onActivityResult).

   Ponto importante

   • O fluxo é síncrono em termos de UX (o usuário vê as telas do POS), mas o resultado é recebido depois, quando o Android devolve o controle ao seu app.

4. Como validar a resposta no onActivityResult

   A documentação traz um exemplo de implementação para validar o retorno: 

   Pagamento | 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);
           }
       }
   }

• Interpretação do fluxo: 

  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
  • Se data == null ou bundle == null: a operação foi cancelada (sem dados).
  • Se resultCode != RESULT_OK: houve erro; tente ler textoEspecialOperador para saber o motivo.
  • Se resultCode == RESULT_OK: percorra o bundle e leia todos os campos (status, valor, NSU etc.) para registrar a transação.

  Pontos de atenção

• Sempre trate o caso de cancelamento e erro para informar corretamente ao usuário e ao sistema.

• Use logs durante desenvolvimento para entender todos os campos que estão vindo.

1. Parâmetros da resposta (dados retornados no bundle)

   A documentação lista os principais campos que podem ser retornados após o pagamento: 

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

   • Campos de resposta

     Campo	Tipo	Descrição
     identificacao	string	ID único da operação (o mesmo enviado).
     valorTotal	string	Valor total da transação.
     statusTransacao	string	"0" = sucesso; outros valores indicam falha.
     nomeRede	string	Nome da adquirente (rede de cartão).
     tipoTransacao	string	Tipo da transação (código usado).
     numeroTransacao	string	Número sequencial da transação (NSU).
     codigoAutorizacaoTransacao	string	Código de autorização da adquirente.
     quantidadeParcelas	string	Número de parcelas.
     dataTransacaoComprovante	string	Data da transação (formato ddMMyyyy).
     horaTransacaoComprovante	string	Hora da transação (formato hhmmss).
     numeroTransacaoCancelada	string	Nº da transação que foi cancelada (usado em estorno).
     timestampTransacaoCancelada	string	Timestamp da transação cancelada (ddMMhhmmss).
     finalizacao	string	Dados técnicos da finalização da transação.
     quantidadeLinhasComprovante	string	Qtde de linhas do comprovante.
     textoEspecialOperador	string	Mensagem para exibição ao operador (erro, status, instruções).
     numeroSerieTerminal	string	Número de série do terminal (SmartPOS).
     executada	boolean	Indica se a operação foi processada com sucesso.
     cnpj	string	CNPJ do estabelecimento.
     bandeiraCartao	string	Bandeira do cartão (ex.: MASTERCARD).

   Pontos de atenção

   • Campo chave: statusTransacao
     
     • "0" → transação aprovada.
     • Diferente de "0" → falha ou cancelamento; use textoEspecialOperador para detalhar.
   • Armazene sempre: identificacao, valorTotal, statusTransacao, numeroTransacao, codigoAutorizacaoTransacao, bandeiraCartao, nomeRede.

2. Fluxo recomendado dentro do seu app Android

   1. Preparar os dados da venda

      • Defina identificacao (ID interno da venda), valorTotal, tipoTransacao, quantidadeParcelas, imprimirComprovante.

   2. Criar e enviar o Intent

      • Use ConnectTEFAdapter ou lógica própria para:
      • Montar o Intent com extras.
      • Verificar se o app ConnectTEF está disponível.
      • Chamar startActivityForResult(...).

   3. Tratar o retorno no onActivityResult

      • Verifique se data e bundle não são nulos.
      • Se resultCode != RESULT_OK, leia textoEspecialOperador e registre erro/cancelamento.
      • Se resultCode == RESULT_OK, leia statusTransacao e demais campos.

   4. Atualizar o sistema interno

      • Se statusTransacao == "0":
      • Marque a venda como paga.
      • Registre NSU, código de autorização, bandeira, valor etc.
      • Se falha:
      • Mostre mensagem ao usuário.
      • Permita nova tentativa ou outra forma de pagamento.

   Ponto importante

   • Não conclua processos internos (como emissão de nota fiscal, baixa definitiva de estoque) sem antes validar statusTransacao e garantir que a transação foi aprovada.

3. Boas práticas de implementação

   • Persistência:
     • Guarde identificacao, statusTransacao, numeroTransacao, codigoAutorizacaoTransacao, valorTotal, bandeiraCartao e nomeRede para conciliação financeira.
   • Tratamento de erros:
     • Use textoEspecialOperador para informar ao usuário o motivo do erro (ex.: cartão recusado, comunicação falhou).
   • Logs e monitoramento:
     • Durante desenvolvimento, registre todos os campos do bundle (for (String key : bundle.keySet()...)) para entender o comportamento real.
   • UX:
     • Informe claramente ao usuário quando a operação for cancelada ou falhar, e ofereça opções (tentar novamente, escolher outro meio de pagamento).

Informações Importantes

• Função da integração via Intent – Pagamento: permite que um app Android realize pagamentos em SmartPOS usando o ConnectTEF, sem precisar implementar APIs, certificados e Webhooks diretamente. 
  Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
• Campos essenciais de envio:
  • identificacao, valorTotal, tipoTransacao, quantidadeParcelas, imprimirComprovante. 
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
• Campos essenciais de resposta:
  • statusTransacao (sucesso/falha), numeroTransacao (NSU), codigoAutorizacaoTransacao, bandeiraCartao, nomeRede, valorTotal, textoEspecialOperador. 
    Pagamento | Conecte seu sistema a múltiplas adquirentes com facilidade
• Critério de sucesso:
  • statusTransacao == "0" e resultCode == RESULT_OK.
• Benefícios de seguir corretamente o procedimento:
  • Pagamentos integrados de forma segura, simples e padronizada.
  • Melhor rastreabilidade financeira (NSU, códigos de autorização, bandeira, rede).
  • Redução de erros de integração, pois o ConnectTEF assume a lógica TEF.
• Recomendações gerais:
  • Utilize este guia na sua base de conhecimento interna para treinar desenvolvedores Android.
  • Implemente primeiro o fluxo de Pagamento, depois avance para Estorno via Intent usando estrutura semelhante.
  • Teste sempre em ambiente controlado (SmartPOS de homologação) antes de liberar para produção.

Este texto está pronto para ser copiado em um documento Word da sua base de conhecimento. Basta aplicar o padrão: título com fonte 34, demais 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.