React Native

O pacote @malvo/react-native-connect embute o widget hospedado do Malvo Connect ({baseUrl}/connect?token=...) dentro de uma react-native-webview e converte os eventos postMessage do widget em callbacks JavaScript.

Toda a conectividade fala com um único host de API, https://api.malvo.io. O widget e o dashboard ficam em https://malvo.io. Não há iniciação de pagamento (ITP) — o widget só conduz consentimentos de agregação de dados (Items).

Pré-requisitos

O único dado obrigatório é um Connect Token gerado pelo seu backend. O clientId/clientSecret ficam apenas no servidor e nunca devem ir para o app. A cadeia de geração é:

Autentique o cliente

POST /auth com clientId + clientSecret no seu backend devolve um apiKey (TTL de 2h).

Gere o Connect Token

POST /connect_token (com X-API-KEY: <apiKey>) devolve um accessToken com TTL de 30 minutos.

Entregue o token ao app

O app recebe esse accessToken e o passa em connectToken. Gere um token novo a cada montagem do widget.

Nunca embarque clientId/clientSecret no app. Esses segredos vivem só no servidor; o app só conhece o connectToken de 30 minutos.

Instalação

npm install @malvo/react-native-connect react-native-webview

react-native e react-native-webview são peer dependencies. Siga o setup de plataforma do react-native-webview — no iOS rode a instalação de pods:

cd ios && pod install && cd ..

Uso

Renderize o componente MalvoConnect dentro de um <Modal> para apresentá-lo em tela cheia:

import { Modal } from "react-native";
import { MalvoConnect } from "@malvo/react-native-connect";

type Props = {
  token: string;
  visible: boolean;
  onClose: () => void;
};

function ConnectModal({ token, visible, onClose }: Props) {
  return (
    <Modal visible={visible} animationType="slide" onRequestClose={onClose}>
      <MalvoConnect
        connectToken={token}
        baseUrl="https://malvo.io"
        includeSandbox={__DEV__}
        onSuccess={({ item }) => {
          console.log("connected", item.id);
          onClose();
        }}
        onError={(error) => console.warn(error.code, error.message)}
        onClose={onClose}
      />
    </Modal>
  );
}

Webhooks são a fonte da verdade. O onSuccess é apenas UX best-effort — o usuário pode fechar o app antes dele disparar. Persista as conexões a partir dos webhooks item/created / item/updated no seu backend. Veja Webhooks.

Sandbox em desenvolvimento

Use includeSandbox={__DEV__} para exibir os conectores de sandbox apenas em builds de desenvolvimento. Não existe um domínio separado de sandbox: ela é opt-in por requisição.

Fluxo de atualização (update item)

Para reautenticar um item existente (LOGIN_ERROR, WAITING_USER_INPUT ou consentimento OUTDATED), gere um update token com itemId no corpo do POST /connect_token e passe esse mesmo id em updateItem:

<MalvoConnect
  connectToken={updateToken}
  updateItem="item-id-uuid"
  onSuccess={({ item }) => console.log(item.status)}
/>

Open Finance / OAuth

Por padrão, o consentimento bancário roda dentro da WebView e retoma o fluxo automaticamente via /connect/finish — sem setup extra. Para instituições que recusam WebViews embarcadas, configure o URI completo em oauthRedirectUri e registre o deep link correspondente:

Passe o oauthRedirectUri ao gerar o token

No POST /connect_token do seu backend, informe options.oauthRedirectUri casando com o seu scheme, por exemplo malvo://oauth-callback.

Defina oauthRedirectUri no componente

Passe o mesmo URI completo ao MalvoConnect, por exemplo oauthRedirectUri="malvo://oauth-callback".

Registre o scheme nativamente

Declare o scheme no iOS (CFBundleURLTypes) e no Android (intent-filter), como abaixo.

No retorno, o SDK compara protocolo, host, porta, caminho, userinfo e qualquer query estática do URI configurado. Além disso, exige que o malvoFlowId reservado, acrescentado pelo backend, coincida com o connectTokenId do Connect Token atual antes de retomar a rota autenticada /connect?token=...&resumeItemId=.... Se o processo foi recriado, o host precisa restaurar com segurança o mesmo Connect Token ainda válido; o SDK não persiste o token e o callback nunca carrega bearer. O initial link só é reivindicado pela instância cujo fluxo corresponde. A bridge nativa também exige malvoBridgeNonce igual ao claim separado bridgeNonce do token e remove esse campo antes dos callbacks. Bearer, code bancário e malvoFlowId nunca atravessam a bridge JavaScript.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>malvo</string>
    </array>
  </dict>
</array>

<activity android:name=".MainActivity">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="malvo" android:host="oauth-callback" />
  </intent-filter>
</activity>

O mesmo oauthRedirectUri precisa ser enviado pelo backend no objeto options do POST /connect_token e pelo app ao componente. oauthRedirectScheme continua disponível apenas para compatibilidade e valida somente o scheme; prefira sempre o URI completo. Não acrescente malvoFlowId: ele é gerado e controlado pela Malvo.

Props

string

required

O Connect Token de 30 minutos gerado pelo seu backend. Única prop obrigatória.

string

default:"https://malvo.io"

Origem que serve o widget hospedado.

boolean

Exibe conectores de sandbox (use __DEV__).

string

Id de um item para o fluxo de atualização. O connectToken deve ter sido gerado com esse mesmo itemId.

string

URI completo do app (ex.: malvo://oauth-callback) para validar e capturar o retorno do OAuth aberto no navegador do sistema.

string

Compatibilidade legada baseada somente no scheme. Não use em novas integrações.

Prop	Tipo	Notas
`connectToken`	`string`	Obrigatória. Token de 30 min do seu backend.
`baseUrl`	`string`	Origem que serve o widget. Padrão `https://malvo.io`.
`includeSandbox`	`boolean`	Exibe conectores de sandbox.
`updateItem`	`string`	Id do item para o fluxo de atualização.
`connectorTypes` / `connectorIds` / `countries` / `language` / `selectedConnectorId`	—	Filtros / dicas de UX.
`oauthRedirectUri`	`string`	URI completo preferencial para validar o retorno OAuth externo.
`oauthRedirectScheme`	`string`	Legado; valida somente o scheme.
`onSuccess` / `onError` / `onOpen` / `onClose` / `onEvent`	callbacks	Callbacks de ciclo de vida do widget.

Callbacks

Callback	Assinatura	Dispara quando
`onSuccess`	`({ item }) => void`	Conexão (ou atualização) concluída. `item` traz ao menos `id`, `status`, `connector`.
`onError`	`(error) => void`	Falha. `error = { code, message, itemId? }`.
`onOpen`	`() => void`	Widget exibido.
`onClose`	`() => void`	Widget fechado (sucesso ou cancelamento).
`onEvent`	`(event) => void`	Recebe `OPEN`, `malvo:success`, `malvo:error` e `malvo:close`; falhas do OAuth externo também usam `malvo:error`.

Próximos passos

Connect Widget — visão geral e opções completas.
Expo — usar o mesmo pacote em apps Expo.
Webhooks — a fonte da verdade para persistir conexões.

Visão geral

Web & JavaScript

Mobile

React Native

Pré-requisitos

Instalação

Uso

Sandbox em desenvolvimento

Fluxo de atualização (update item)

Open Finance / OAuth

Props

Callbacks

Próximos passos

​Pré-requisitos

​Instalação

​Uso

​Sandbox em desenvolvimento

​Fluxo de atualização (update item)

​Open Finance / OAuth

​Props

​Callbacks

​Próximos passos

Pré-requisitos

Instalação

Uso

Sandbox em desenvolvimento

Fluxo de atualização (update item)

Open Finance / OAuth

Props

Callbacks

Próximos passos