Connectors

Um Connector é uma instituição financeira em um país e contexto de usuário específicos. Ele declara quais dados o usuário precisa fornecer, quais produtos suporta e sua saúde operacional. Uma mesma marca pode aparecer em mais de um país ou em conectores separados para pessoa física e empresarial. Cada Item é criado a partir de um connector.

IDs são opacos

O id é um inteiro persistido e estável para aquele conector, mas não identifica o provedor, país ou tipo de usuário. Não aplique regras por faixa e não mantenha um catálogo hardcoded. Use os campos country, type, isOpenFinance, isSandbox, products e health retornados pela API. Os IDs 0–7 permanecem reservados aos conectores locais de sandbox por compatibilidade. IDs de instituições reais são atribuídos pelo diretório da Malvo quando a instituição aparece pela primeira vez.

Conectividade unificada

Na Malvo, o mesmo contrato público roteia cada Connector pela infraestrutura operacional adequada. Essa infraestrutura é um detalhe interno: use as capacidades declaradas no objeto, não tente inferi-la pelo ID. Fluxos regulados usam autorização no banco. | Origem do catálogo | Produtos anunciados | Jornada de conexão | |---|---|---|---| | Open Finance Brasil | Varia por instituição | cpf ou cnpj e redirect regulado | | Open Banking internacional (AIS) | ACCOUNTS, TRANSACTIONS | Redirect; alguns ASPSPs pedem seleção prévia de método | | Conectividade compatível | Varia por Connector | Autorização regulada, OAuth, MFA ou ação no app da instituição | O catálogo entregue ao widget mantém uma única lista visual de instituições, sem agrupamento ou identificação de provedor. A separação permanece apenas na camada interna da Malvo. supportsPaymentInitiation permanece sempre false.

Cobertura internacional

AT BE BG HR CY CZ DK EE FI FR DE GR HU IS IE IT LV LI LT LU MT NL NO PL PT RO SK SI ES SE GB

Essa allowlist de 31 países é um limite de configuração, não uma garantia de todos os bancos. A Malvo publica somente as instituições AIS ativas nas jurisdições contratadas. Ambiente, contrato e disponibilidade operacional podem alterar o catálogo; consulte GET /connectors em runtime.

Shape do objeto Connector (resumo)

Exemplo ilustrativo de um conector AIS; o id real deve ser obtido por GET /connectors:

{
  "id": 742,
  "name": "Example Bank",
  "institutionUrl": "https://example-bank.invalid",
  "imageUrl": "https://malvo.io/connectors/example-bank.svg",
  "primaryColor": "1A56DB",
  "country": "FI",
  "type": "PERSONAL_BANK",
  "credentials": [],
  "products": ["ACCOUNTS", "TRANSACTIONS"],
  "isOpenFinance": true,
  "isSandbox": false,
  "oauth": true,
  "oauthUrl": null,
  "hasMFA": false,
  "supportsPaymentInitiation": false,
  "health": { "status": "ONLINE", "stage": null },
  "createdAt": "2024-06-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z"
}

Campos de destaque:

Campo	Tipo	Notas
`id`	number	Inteiro estável para o conector; trate como opaco e obtenha via API
`name`	string	Nome de exibição da instituição
`primaryColor`	string	Hex sem prefixo `#` (ex. `"820AD1"`)
`country`	string	ISO-3166-1 alpha-2 (ex. `"BR"`, `"FI"` ou `"GB"`)
`type`	enum	`PERSONAL_BANK`, `BUSINESS_BANK`, `INVESTMENT` ou `OTHER`
`credentials`	array	Descreve somente os campos exigidos pelo fluxo regulado atual, como `cpf`/`cnpj` ou uma seleção de jornada
`products`	string[]	Produtos anunciados por este conector (ver Products)
`isOpenFinance`	boolean	`true` = conector regulado de Open Finance/Open Banking
`isSandbox`	boolean	`true` = connector de testes (só visível com `sandbox=true`)
`oauth`	boolean	`true` = conexão requer redirect OAuth à instituição
`oauthUrl`	string \| null	URL de autorização efêmera, preenchida no contexto de criação/reconsentimento do Item
`hasMFA`	boolean	`true` = pode levantar um desafio de MFA durante a conexão
`supportsPaymentInitiation`	boolean	Sempre `false` na Malvo (mantido por compatibilidade)
`health`	object	`{ "status": "ONLINE" \| "OFFLINE" \| "UNSTABLE", "stage": "BETA" \| null }`

No fluxo internacional, authMethod aparece somente quando a seleção via API é útil ou obrigatória para um método que a interface hospedada não mostra. Com vários métodos ocultos ele é obrigatório; quando há também métodos visíveis, é opcional e a omissão deixa a interface hospedada conduzir a escolha. Um único método oculto é selecionado automaticamente. Use apenas value retornado em credentials[].options; a Malvo valida a opção novamente e não aceita nomes forjados. Senha, token e demais credenciais bancárias continuam sendo coletados pela interface hospedada de autorização, nunca pela Malvo ou pelo integrador.

GET /connectors — listar connectors

Header X-API-KEY obrigatório. Retorna o envelope de paginação padrão.

curl "https://api.malvo.io/connectors?isOpenFinance=true&countries=FI&name=nordea" \
  -H "X-API-KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

const res = await fetch(
  "https://api.malvo.io/connectors?isOpenFinance=true&countries=FI&name=nordea",
  { headers: { "X-API-KEY": apiKey } }
);

const { results } = await res.json();

Resposta 200:

{
  "total": 1,
  "totalPages": 1,
  "page": 1,
  "results": [ { "id": 742, "name": "Nordea", "country": "FI" } ]
}

Filtros disponíveis

Param	Tipo	Comportamento
`name`	string	Match parcial case-insensitive no `name`
`countries`	string	ISO-3166-1 alpha-2, separado por vírgula (ex. `BR` ou `FI,SE,GB`)
`types`	string	Filtra por `type` (enum), separado por vírgula
`sandbox`	boolean	Default `false`. `true` inclui connectors de sandbox no resultado
`isOpenFinance`	boolean	`true` → somente conectores regulados de Open Finance/Open Banking

Em uma aplicação de produção, connectors de sandbox só entram em GET /connectors com sandbox=true ou includeSandbox=true. Uma aplicação de sandbox enxerga somente connectors de sandbox. No Connect Widget, a lista final também respeita a allowlist de países, tipos e IDs configurada para a aplicação e os filtros enviados pelo SDK.

Não hardcode o catálogo

O mesmo ASPSP pode existir em mais de um país, expor contextos pessoal e empresarial separados ou mudar de disponibilidade. Carregue o catálogo ao abrir o fluxo, persista apenas o connectorId selecionado no Item e reapresente GET /connectors quando o usuário precisar reconectar.

Connectors locais de sandbox base (0–7)

Os IDs 0–99 são reservados para connectors locais de sandbox. Estes são os oito cenários base; o catálogo também pode conter bancos curados e ASPSPs Enable de simulação:

ID	Nome	Fluxo	`type`	`isOpenFinance`
0	Malvo Bank	Fluxo básico (user/pass + 1 campo de MFA)	`PERSONAL_BANK`	false
1	Malvo Bank Caixa-style	Fluxo básico, variante Caixa	`PERSONAL_BANK`	false
2	Malvo Bank Business	Conta empresarial	`BUSINESS_BANK`	false
3	Malvo Bank MFA-1	MFA de fator único (token no formulário inicial)	`PERSONAL_BANK`	false
4	Malvo Bank MFA-2	MFA em dois passos (pausa em `WAITING_USER_INPUT`)	`PERSONAL_BANK`	false
5	Malvo Bank Joint	Contas conjuntas	`PERSONAL_BANK`	false
6	Malvo Bank QR	Login via QR	`PERSONAL_BANK`	false
7	Malvo Bank Open Finance	Fluxo OF (só CPF → redirect OAuth mock)	`PERSONAL_BANK`	true

Os gatilhos de comportamento do sandbox (credenciais de teste, usernames que disparam erros etc.) estão na página de Sandbox.

A cobertura de instituições é dinâmica em todas as rotas. Consulte GET /connectors?isOpenFinance=true em runtime em vez de hardcodar IDs ou a matriz de capacidades. Veja também Lista de connectors.

Lista de connectors

Catálogo de referência das instituições suportadas.

Items

Crie uma conexão a partir de um connector.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

IDs são opacos

Conectividade unificada

Cobertura internacional

Shape do objeto Connector (resumo)

GET /connectors — listar connectors

Filtros disponíveis

Não hardcode o catálogo

Connectors locais de sandbox base (0–7)

Lista de connectors

Items

​IDs são opacos

​Conectividade unificada

​Cobertura internacional

​Shape do objeto Connector (resumo)

​GET /connectors — listar connectors

​Filtros disponíveis

​Não hardcode o catálogo

​Connectors locais de sandbox base (0–7)

Lista de connectors

Items

IDs são opacos

Conectividade unificada

Cobertura internacional

Shape do objeto Connector (resumo)

GET /connectors — listar connectors

Filtros disponíveis

Não hardcode o catálogo

Connectors locais de sandbox base (0–7)