Widget de conexão bancária: construir ou embarcar

A tela em que o seu usuário escolhe o banco e autoriza o acesso parece a parte simples do projeto. Uma lista de instituições, um botão, um redirecionamento.

Ela é a parte em que o projeto inteiro é ganho ou perdido. Se o usuário não terminar esse fluxo, nada do que você construiu depois existe para ele.

O conceito

Um widget de conexão bancária é o componente que leva o usuário de "quero conectar minha conta" até "conectado", passando por seleção de instituição, autorização no banco e volta para o seu produto.

Dá para construir o seu. A pergunta é se vale, e a resposta depende de quantos casos de borda você está disposto a tratar.

O que dá errado nesse fluxo

Essa é a lista que ninguém imagina na primeira versão e todo mundo descobre na terceira semana.

• O usuário não acha o banco dele. A lista tem dezenas de instituições com nomes parecidos, variação de nome fantasia e razão social, e PF e PJ no mesmo lugar.
• Ele escolhe o conector errado. Muitas instituições têm entrada separada para pessoa física e jurídica, e escolher a errada leva a um erro que não explica nada.
• O banco pede MFA no meio. Token, SMS, confirmação no app. O fluxo precisa parar, pedir, esperar e retomar sem perder o estado.
• O OAuth abre numa webview e quebra. Em aplicativo, abrir a autorização do banco dentro de uma webview dá problema com parte das instituições. Algumas só funcionam no navegador do sistema.
• O redirecionamento não volta. O usuário autoriza no banco e, dependendo da plataforma e do dispositivo, o retorno para o seu app não acontece sozinho.
• O usuário sai no meio. Fecha o app, troca de aba, atende o telefone. A conexão pode terminar com sucesso depois disso, e o seu frontend nunca fica sabendo.
• A autorização demora muito. Existe instituição em que o usuário precisa autorizar o acesso como dispositivo confiável, e o processo leva cerca de meia hora. O fluxo precisa dizer isso sem parecer que travou.
• O usuário precisa reconectar e você manda ele começar do zero. Consentimento vence, credencial muda. Atualizar uma conexão existente é um fluxo diferente de criar uma nova.
• Erro do banco chega como código. Se a mensagem que o usuário vê for o erro bruto da instituição, ele abre chamado. Sempre.

Nenhum desses é difícil sozinho. Todos juntos, mantidos ao longo do tempo, são um produto.

O que a norma define e o que é escolha sua

Uma dúvida comum: quanto desse fluxo dá para redesenhar?

O que não é seu: a tela de autenticação do banco e a tela de consentimento dentro do banco. O usuário digita a senha dele no ambiente da instituição, e é exatamente isso que faz o modelo ser seguro. Você não vê nem toca nessas credenciais.

O que é seu: tudo antes e tudo depois. Quando o convite para conectar aparece, como você explica o porquê, quais instituições você mostra, o que acontece em caso de erro, e o que o usuário vê quando volta.

Na prática, a maior parte da taxa de conclusão se decide na parte que é sua, não na que é regulada.

Construir o próprio: o que você assume

Se o caminho for construir, essa é a lista do que passa a ser seu para sempre.

A lista de instituições e o estado de cada uma. Nome, logo, tipo, se está operando agora. Instituição entra, sai e fica instável.

Todos os formatos de autenticação. Usuário e senha, OAuth com redirecionamento, MFA síncrono, MFA assíncrono. Cada combinação é uma tela e um estado.

O comportamento por plataforma. Web, app Android, app iOS. Cada um lida de um jeito com redirecionamento e webview.

A máquina de estados. Em andamento, aguardando MFA, aguardando autorização do usuário, erro recuperável, erro final. E o que mostrar em cada um.

O ciclo de atualização. Conexão que precisa de nova credencial, consentimento que vence, item que precisa ser renovado em vez de recriado.

As mensagens de erro. Traduzir erro de instituição para frase que um humano entende é trabalho contínuo, porque as instituições mudam os erros.

Faz sentido construir quando a tela de conexão é parte central da sua proposta, ou quando você cobre tão poucas instituições que a combinatória é pequena.

Embarcar pronto: o que você abre mão

E aqui o outro lado, com a mesma honestidade.

Você abre mão de controle total do visual. Um widget pronto oferece ajustes, não liberdade de design. Se o seu produto tem um sistema de design rigoroso, essa tela vai parecer um pouco de fora.

Você abre mão de controlar a ordem das etapas. O fluxo é o que ele é, e você configura o que entra e o que fica de fora, não a sequência.

E você depende do ciclo de releases de outra pessoa para mudanças no fluxo.

O que você ganha em troca é não ter que descobrir sozinho cada um dos nove itens da lista lá de cima.

E a Pluggy nisso tudo?

O Pluggy Connect é esse componente pronto, e vale falar do que ele deixa você decidir.

O que você configura: quais instituições aparecem (por id, por tipo ou por país), quais produtos são buscados, tema claro ou escuro, idioma, se abre em tela cheia ou modal no celular, e se o usuário pode minimizar e continuar a conexão em segundo plano. Dá para pular a seleção de instituição e ir direto para uma, e dá para pré-preencher CPF ou CNPJ nos conectores de Open Finance.

O que ele resolve por você: os formatos de autenticação, o MFA, a volta do OAuth e o problema de webview. Existe inclusive um parâmetro para forçar o OAuth a abrir no navegador do sistema em vez da webview, justamente porque esse é um caso de borda conhecido em aplicativo.

O que ele te dá de visibilidade: eventos de cada etapa do fluxo, de aceitar os termos até concluir o login. É com eles que você mede onde o usuário desiste, em vez de supor.

E um detalhe que economiza muita dor de cabeça: não conte com o callback de sucesso no frontend para a sua regra de negócio. Se o usuário fechar o app no meio, você nunca recebe. A conexão pode terminar bem mesmo assim, e quem te avisa disso é o webhook no seu backend. Existe instituição em que a autorização leva cerca de 30 minutos e o sucesso só chega por webhook.

Os SDKs existem para React, React Native, Flutter e JavaScript puro, e a referência completa de parâmetros está na documentação.

Se você ainda está decidindo quais instituições cobrir, vale entender a diferença entre conector regulado e acesso direto, porque ela muda o fluxo que o usuário vê.

Perguntas frequentes

Dá para deixar o widget com a minha marca?

Dá para ajustar tema, idioma, modo de exibição e quais instituições aparecem. Não é liberdade total de design, e é honesto dizer isso antes.

O meu usuário digita a senha do banco no meu produto?

Não. A autenticação acontece no ambiente da instituição.

Posso pular a tela de seleção de banco?

Pode, informando o conector de antemão. Faz sentido quando o seu produto já sabe qual instituição o usuário usa.

Como eu sei onde o usuário desistiu?

Pelos eventos do fluxo. Eles marcam cada etapa, então dá para montar o funil de conexão com dado em vez de palpite.

E quando a conexão precisa ser renovada?

É um fluxo próprio de atualização, apontando para a conexão existente, e não uma conexão nova.

Funciona em aplicativo?

Funciona, com SDK para React Native e Flutter. A atenção em app é com o comportamento do OAuth, e existe configuração específica para isso.

Conclusão

A tela de conexão é onde o seu usuário decide se confia no que vem depois. Ela merece atenção, só que quase sempre a atenção que ela merece está no contexto em volta, não na mecânica do fluxo.

Se quiser ver como é a experiência antes de decidir construir, dá para rodar o fluxo com o conector de testes sem conectar conta real nenhuma.