Os conectores regulados redirecionam o usuário para a jornada de autorização da instituição. No Brasil, a Malvo usa Open Finance Brasil; nos países internacionais habilitáveis, usa Open Banking AIS. A sua aplicação nunca recebe senha bancária e consome o mesmo contrato de Item nos dois fluxos. Para que o usuário volte ao lugar certo depois de autorizar no banco, você configura um oauthRedirectUri.

​
Regras do oauthRedirectUri

O oauthRedirectUri precisa ser HTTPS ou um deep link de mobile. http:// e localhost são explicitamente rejeitados, assim como URLs relativas, com credenciais embutidas, fragmento ou esquemas perigosos (javascript:, data:, file:, ftp:, ws: e wss:).
Exemplos válidos:
  • https://seu.app/oauth/callback
  • meuapp://oauth/callback
O oauthRedirectUri sempre é autorizado server-side, em um de dois lugares:
  • no objeto options do POST /connect_token, ou
  • diretamente no POST /items, quando você cria o Item server-side.
No widget hospedado/JavaScript e no React web, não há prop local adicional. Nos SDKs React Native, Expo e Flutter, passe também o mesmo URI completo ao componente para que o app valide o deep link e retome o fluxo com segurança.

​
Prioridade de resolução

Se o oauthRedirectUri estiver definido tanto no nível do connect token quanto no nível de criação do Item, o valor do Item vence (o mais específico sobrescreve o mais genérico). Ao concluir, a Malvo preserva a query string já existente e acrescenta: malvoFlowId, itemId, status e message são nomes reservados: não os inclua na query do oauthRedirectUri. O backend rejeita os três campos de resultado e controla malvoFlowId. Esse identificador acompanha qualquer callback criado por Connect Token; nos SDKs React Native e Flutter, o valor é conferido automaticamente com o token antes de retomar o WebView e removido antes de carregar a rota interna de continuação. Se você não informar oauthRedirectUri, o callback retorna à página de finalização hospedada do Connect Widget.

​
Comportamento por plataforma

O widget abre a jornada de autorização. Após o callback, a página de finalização comunica o resultado à janela pai; o onSuccess continua sendo um callback de UX, não uma confirmação autoritativa de que todos os dados já foram sincronizados.

​
Chamada de exemplo (connect token)

​
Alternativa server-side (sem widget)

Você pode pular o widget por completo. No POST /items com X-API-KEY, o payload aceita oauthRedirectUri, e a resposta inclui a URL efêmera em connector.oauthUrl. Redirecione o usuário uma única vez e use o estado do Item e os webhooks da Malvo para saber quando a coleta terminou.
O connectorId acima é apenas ilustrativo. Obtenha o valor atual por GET /connectors. Para Open Finance Brasil, preencha em parameters os campos declarados por connector.credentials; no fluxo internacional, parameters normalmente é {}. Quando o ASPSP publicar mais de um método de autenticação, o connector declara um select chamado authMethod; envie exatamente uma das opções anunciadas. Essa escolha não é senha bancária: a interface da Enable continua coletando diretamente as credenciais do usuário. Recomenda-se um clientUserId estável para correlação e avoidDuplicates.

​
Atualização e reconsentimento

Renove sempre no mesmo Item:
  1. Crie um update token com POST /connect_token, passando o itemId existente e o oauthRedirectUri em options.
  2. Abra o widget com updateItem igual ao itemId do token; ele mantém o mesmo conector.
  3. Se preferir integração server-side, chame PATCH /items/{id}. Quando o consentimento estiver morto ou expirado, a resposta traz uma nova URL em connector.oauthUrl; quando ele ainda for válido, a Malvo apenas agenda um refresh.
  4. Após a autorização, reconsulte GET /items/{id} e os produtos. Não crie outro Item.
Um update token é vinculado ao Item e não pode ser usado para atualizar outro itemId ou trocar de instituição.

​
Callback do provedor e callback da sua aplicação

São URLs diferentes:
  • A infraestrutura internacional retorna ao callback fixo da Malvo (por exemplo, https://api.malvo.io/connect/oauth/callback).
  • Depois de validar state e trocar o code por uma sessão, a Malvo redireciona para o oauthRedirectUri do Item, com itemId e status.
O integrador não troca o code upstream e nunca deve receber ou armazenar a sessão da infraestrutura de conectividade.
O link de autorização é single-use/efêmero: ele só deve ser aberto uma vez. Não o envie por canais que geram pré-visualização de link (apps de mensagem, e-mails com link preview) — o preview pode consumir a URL e a autorização do usuário falhar. Entregue o link diretamente ao usuário, no próprio fluxo, e não o registre em logs.
No fluxo internacional, a Malvo consulta a sessão e os dados por scheduler/refresh e então emite os seus webhooks de Item e transação. Esses webhooks da Malvo continuam sendo a fonte de verdade para a sua integração.

​
Próximos passos

Visão geral do widget

Parâmetros, callbacks e o diagrama de sequência completo.

Modo de atualização

Renove consentimentos OUTDATED reabrindo o redirect OAuth.