Sandbox

O Sandbox da Malvo reproduz o ciclo de vida de um Item sem conectar contas reais e sem gerar cobrança. Ele inclui conectores mockados locais e pode incluir conectores AIS internacionais quando essa modalidade está habilitada no ambiente SANDBOX.

O Sandbox usa o mesmo host https://api.malvo.io; o isolamento vem de uma aplicação Malvo com environment: SANDBOX e seu próprio clientId/clientSecret. Não há subdomínio ou base URL de API separados.

Opt-in: como ligar o Sandbox

Uma aplicação SANDBOX enxerga somente conectores com isSandbox: true. Em listagens feitas com uma aplicação de produção, os mocks locais ficam ocultos por padrão e podem ser incluídos explicitamente para desenvolvimento:

Onde	Como ativar
`GET /connectors` (server-side)	Parâmetro de query `sandbox=true`
Connect Widget	Opção de configuração `includeSandbox: true`

curl "https://api.malvo.io/connectors?sandbox=true" \
  -H "X-API-KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

const connect = new MalvoConnect({
  connectToken,
  includeSandbox: true,
});

Mantenha sandbox/includeSandbox desligado em produção. Os conectores de sandbox só devem aparecer em ambientes de teste e desenvolvimento.

Conectores mockados locais

A faixa de IDs 0–99 é reservada para conectores locais de sandbox. Os ativos vão de 0 a 7. Todos têm isSandbox: true.

ID	Nome	Tipo de 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	Fluxo de conta empresarial	`BUSINESS_BANK`	false
3	Malvo Bank MFA-1	MFA de fator único (token no formulário inicial, credencial `mfa: true`)	`PERSONAL_BANK`	false
4	Malvo Bank MFA-2	MFA em dois passos (QR + seleção; pausa em `WAITING_USER_INPUT`)	`PERSONAL_BANK`	false
5	Malvo Bank Joint	Contas conjuntas (estilo “Conta Conjunta”)	`PERSONAL_BANK`	false
6	Malvo Bank QR	Login via QR	`PERSONAL_BANK`	false
7	Malvo Bank Open Finance	Fluxo Open Finance (só CPF → redirect OAuth para banco mock)	`PERSONAL_BANK`	true

Os conectores 0–6 usam um fluxo de credenciais no campo parameters do POST /items — apenas para exercitar cenários de teste (MFA, conta conjunta, QR etc.) no sandbox. O conector 7 simula o fluxo de redirecionamento do Open Finance, que é como todas as conexões de produção funcionam.

Credenciais default

Use estes valores para todos os conectores de fluxo básico:

Campo	Valor
Password	`password-ok`
MFA token	`123456`

Qualquer password diferente de password-ok resulta em INVALID_CREDENTIALS → LOGIN_ERROR. Qualquer MFA token diferente de 123456 resulta em INVALID_CREDENTIALS_MFA.

Gatilhos por username

O username enviado controla o desfecho da execução. É assim que você reproduz, sob demanda, cada estado terminal do Item.

Username	Desfecho
`user-ok`	Conexão bem-sucedida → `UPDATED` / `SUCCESS`
`user-locked`	`LOGIN_ERROR` com `executionStatus: ACCOUNT_LOCKED`
`user-unavailable`	`OUTDATED` com `executionStatus: SITE_NOT_AVAILABLE`
`user-error`	`OUTDATED` com `executionStatus: ERROR`
`user-ok-perf-XXx`	Sucesso com XX× o volume normal de transações (máx. `5000x`) — para testes de carga

Testar uma conexão no sandbox

Liste os conectores de sandbox

Chame GET /connectors?sandbox=true para ver os conectores 0–7 e escolher o fluxo que quer testar.

curl "https://api.malvo.io/connectors?sandbox=true" \
  -H "X-API-KEY: <apiKey>"

Crie um Item com as credenciais de teste

Use o gatilho user-ok com a password default para uma conexão bem-sucedida no conector 0.

curl -X POST "https://api.malvo.io/items" \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": 0,
    "parameters": { "user": "user-ok", "password": "password-ok" },
    "products": ["ACCOUNTS", "TRANSACTIONS"]
  }'

Responda ao MFA, se houver

Em conectores de MFA de duas etapas (ex. 4), o Item pausa em WAITING_USER_INPUT. Leia item.parameter para saber o campo esperado e envie o token default.

curl -X POST "https://api.malvo.io/items/{id}/mfa" \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "token": "123456" } }'

Faça polling até o estado final

Consulte GET /items/{id} (ou consuma webhooks) até o status sair de UPDATING/LOGIN_IN_PROGRESS. Com user-ok, o Item chega a UPDATED / SUCCESS e você já pode ler contas e transações.

Reproduza erros à vontade

Repita a criação trocando o username (user-locked, user-unavailable, user-error) para exercitar os caminhos de recuperação da sua integração.

Sandbox de Open Finance (conector 7)

O conector 7 simula o fluxo regulado de Open Finance, com redirecionamento e consentimento:

Informe apenas o CPF

O conector 7 não pede user/password no formulário inicial — apenas o CPF.

curl -X POST "https://api.malvo.io/items" \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorId": 7,
    "parameters": { "cpf": "12345678901" },
    "oauthRedirectUri": "https://your.app/oauth/callback"
  }'

Autorize no banco mock

O usuário é redirecionado para a página de login de um banco mock. Use as credenciais do banco mock:

Campo	Valor
E-mail	`[email protected]`
Password	`P@ssword01`

Volte pelo oauthRedirectUri

Após autorizar, o usuário é redirecionado de volta pelo oauthRedirectUri, o Item executa e chega a UPDATED. O fluxo exercita o consentimento completo: autorizar → redirect → executar.

Sandbox internacional

Quando o ambiente internacional está em modo SANDBOX, o catálogo inclui ASPSPs de simulação. Eles aparecem como conectores isOpenFinance: true, isSandbox: true, sem credenciais bancárias no objeto e com os produtos ACCOUNTS e TRANSACTIONS.

O sandbox internacional contém apenas uma amostra de ASPSPs e pode ter limitações ou instabilidades próprias de cada banco. Ele valida assinatura RSA, redirect, sessão, paginação e mapeamento de dados, mas não comprova a cobertura nem o comportamento de produção. Descubra a lista em runtime e não copie IDs do sandbox para produção.

Garantias do Sandbox

O Sandbox nunca gera cobrança. Nenhuma chamada a conector de sandbox toca em bancos reais nem na rede de Open Finance, e nada é faturado.

Items de sandbox inativos por mais de 30 dias são permanentemente removidos por garbage collection. Não conte com a persistência de longo prazo de Items de teste.
Não há ITP, pagamentos ou iniciação de qualquer tipo no Sandbox — assim como na API de produção, esses recursos não existem na Malvo.

Próximos passos

Connectors

A convenção de IDs e o shape do objeto Connector.

Items

A máquina de estados e os caminhos de recuperação que você vai exercitar no sandbox.

Connect Widget

Ative includeSandbox para testar o fluxo completo na UI.

Quickstart

Conecte um banco de teste de ponta a ponta em minutos.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Opt-in: como ligar o Sandbox

Conectores mockados locais

Credenciais default

Gatilhos por username

Testar uma conexão no sandbox

Sandbox de Open Finance (conector 7)

Sandbox internacional

Garantias do Sandbox

Próximos passos

Connectors

Items

Connect Widget

Quickstart

​Opt-in: como ligar o Sandbox

​Conectores mockados locais

​Credenciais default

​Gatilhos por username

​Testar uma conexão no sandbox

​Sandbox de Open Finance (conector 7)

​Sandbox internacional

​Garantias do Sandbox

​Próximos passos

Connectors

Items

Connect Widget

Quickstart

Opt-in: como ligar o Sandbox

Conectores mockados locais

Credenciais default

Gatilhos por username

Testar uma conexão no sandbox

Sandbox de Open Finance (conector 7)

Sandbox internacional

Garantias do Sandbox

Próximos passos