Sandbox

Usando nosso ambiente de produção, você pode acessar conectores Live e Sandbox. Para fins de teste, você pode experimentar sua integração usando nosso conector Sandbox (que representa nosso ambiente Sandbox). Isso permitirá que você veja como as transações se atualizam ao longo do tempo e teste todas as possíveis conexões válidas e fluxos errôneos. As transações do Sandbox são atualizadas semanalmente e podem também mudar diariamente, portanto, o ambiente não é estático.

Aviso

Todos os itens do sandbox que não forem atualizados por mais de 30 dias serão excluídos sem possibilidade de recuperação no futuro.

Você encontrará diferentes fluxos:

Fluxo básico (também incluímos um fluxo especial da Caixa)
Fluxo básico para Negócios
MFA 1 etapa
MFA 2 etapas
Contas conjuntas (fluxo Bradesco Conta Conjunta)
Fluxo de Login QR
Fluxo de Open Finance

Para um fluxo bem-sucedido, as credenciais são:

Senha correta: password-ok
Token MFA correto: 123456

Cada nome de usuário de teste abaixo mapeia para um status de execução específico. Veja Ciclo de vida do Item para a descrição completa dos status de item e execução.

Estrutura de resposta do Sandbox #

O Sandbox (conector Pluggy Bank) retorna dados sintéticos, mas com a mesma estrutura de campo que as respostas de produção. Abaixo está o mapeamento de campos observado em /accounts, /transactions, /investments e /loans para um item de teste consultado.

Contas #

// Sempre retorna pelo menos 1 CONTA/BANCÁRIA e 1 CONTA/CARTÃO DE CRÉDITO:
{
    "type": "BANK", "subtype": "CHECKING_ACCOUNT",
    "balance": 21544.6, "currencyCode": "BRL",
    "marketingName": "GOLD Conta Corrente", "taxNumber": "333.333.333-33", "owner": "John Doe",
    "bankData": {
      "transferNumber": "123/0001/12345-0",
      "closingBalance": 21544.6,
      "automaticallyInvestedBalance": 2154.46,
      "hasReservedBalance": true,
      "reservedBalances": [{ "name": "Caixinha Para Férias", "availableAmounts": [{ "amount": 1000.04, "remuneration": { "indexer": "CDI", "rateType": "LINEAR", "preFixedRate": 0.3 } }] }]
    },
    "creditData": null
  }
 
  {
    "type": "CREDIT", "subtype": "CREDIT_CARD",
    "balance": -503.1,
    "creditData": {
      "level": "BLACK", "brand": "MASTERCARD",
      "balanceCloseDate": "2026-07-23", "balanceDueDate": "2026-07-28",
      "creditLimit": 300000, "availableCreditLimit": 300000,
      "minimumPayment": 100.62, "holderType": "MAIN", "status": "ACTIVE"
    }
  }
 
// Note que bankData/creditData são mutuamente exclusivos dependendo do tipo da conta - o Sandbox até simula reservedBalances ("cofrinhos") dentro de bankData, o que não é trivial encontrar documentado em outro lugar.

Transações #

// Transação simples (recorrente, sem metadados extras) — salário, débitos recorrentes:
  { "description": "SALARIO EMPRESA XYZ LTDA", "amount": 8500, "type": "CREDIT", "category": "Salary", "categoryId": "01010000", "paymentData": null,
  "creditCardMetadata": null }
 
// Pagamento de boleto — o único registro com paymentData populado:
  {
    "description": "Pagamento de boleto", "amount": -100, "type": "DEBIT",
    "category": "Transfer - Bank Slip", "categoryId": "05010000",
    "paymentData": {
      "payer": { "documentNumber": { "type": "CPF", "value": "111.111.111-11" }, "name": "Francisco Souza", "routingNumberISPB": "60701190" },
      "paymentMethod": "BOLETO",
      "receiver": { "documentNumber": { "type": "CNPJ", "value": "PL.UGG.Y12/AB00-42" }, "name": "Pluggy Brasil Instituição de Pagamento LTDA" },
      "boletoMetadata": { "baseAmount": 90, "discountAmount": 0, "interestAmount": 10, "digitableLine": "11190000111001113911100000021110600000000111000" }
    }
  }
 
// Compra parcelada no cartão de crédito — o único registro com creditCardMetadata populado:
  {
    "description": "NETFLIX.COM", "amount": -55.9,
    "creditCardMetadata": { "installmentNumber": 2, "totalInstallments": 6, "totalAmount": -335.4, "payeeMCC": 5812, "billId":
  "3b3341e4-d30c-48d6-bcbe-79a3fe47d704" }
  }
 
// Em outras palavras: o Sandbox simula pagamentos de boleto e compras parceladas no cartão, mas a conta corrente consultada aqui não possui transferências Pix, TED ou intercontas — todas as 17 transações da conta corrente são: pagamento de boleto, débitos recorrentes (telecomunicações, eletricidade, taxas de condomínio), salário e pagamento de contas. No cartão de crédito, todas as 9 transações são compras (assinaturas/acadêmia), sem exemplos de disputa, reembolso ou adiantamento em dinheiro.

Investimentos #

// 8 investimentos em 6 combinações de tipo/subtipo:
 
  // SECURITY/PGBL — plano de previdência
  {
    "type": "SECURITY", "subtype": "PGBL", "name": "ITAU Sandbox previdencia",
    "balance": 11720.42, "value": 3.605103, "amount": 1720.42,
    "lastMonthRate": -0.8, "lastTwelveMonthsRate": 5.97, "annualRate": 7.64,
    "issuer": "ITAU UNIBANCO ASSET MANAGEMENT LTDA", "issuerCNPJ": "40.430.971/0001-96"
  }
 
  // SECURITY/RETIREMENT — plano de previdência emitido pela própria Pluggy
  {
    "type": "SECURITY", "subtype": "RETIREMENT", "name": "Pluggy PREVIDENCIA",
    "balance": 1359.39, "amountProfit": 359.39, "amountOriginal": 1000,
    "issuer": "Banco do Pluggy", "dueDate": "2026-07-23T16:16:27.300Z"
  }
 
  // MUTUAL_FUND/INVESTMENT_FUND — aparece duas vezes (Premium/Básico)
  {
    "type": "MUTUAL_FUND", "subtype": "INVESTMENT_FUND", "name": "Fondo de Investimento Premium",
    "balance": 1359.39, "quantity": 3, "value": 500, "amount": 1500,
    "taxes": 40.61, "taxes2": 100, "amountProfit": 359.39, "amountOriginal": 1000
  }
 
  // FIXED_INCOME/CDB — título de renda fixa
  {
    "type": "FIXED_INCOME", "subtype": "CDB", "name": "CDR",
    "balance": 2000, "rate": 150, "rateType": "CDI", "fixedAnnualRate": 2.5,
    "dueDate": "2026-07-23T16:16:27.300Z", "issuer": "Banco do Pluggy",
    "institution": { "name": "BANCO BTG PACTUAL S/A", "number": "30306294000145" }
  }
 
  // ETF/ETF — aparece duas vezes: um ativo, um totalmente retirado
  {
    "type": "ETF", "subtype": "ETF", "name": "ISUS11 STOCK", "code": "ISUS11", "isin": "123456789",
    "quantity": 1, "amount": 2000, "status": "ACTIVE"
  }
  {
    "type": "ETF", "subtype": "ETF", "name": "BOVA11", "code": "BOVA11",
    "quantity": 0, "value": 118.4, "status": "TOTAL_WITHDRAWAL"
  }
 
  // EQUITY/REAL_ESTATE_FUND — REIT (FII)
  {
    "type": "EQUITY", "subtype": "REAL_ESTATE_FUND", "name": "GGRC11", "code": "GGRC11", "isin": "BRGGRCCTF002",
    "quantity": 1, "amount": 118.4, "issuer": "GGR COVEPI RENDA FDO INV IMOB"
  }
 
  // Nenhum exemplo de SECURITY/ação individual (equidade mantida fora de um fundo), e nada explicitamente
  // rotulado como Tesouro Direto — o mais próximo disponível é o FIXED_INCOME/CDB acima.

Empréstimos #

Estes são dados de exemplo

Os valores acima são exemplos ilustrativos do que o Sandbox pode retornar - eles existem para ajudá-lo a construir contra a estrutura de campo correta. O Sandbox não é destinado a ser usado como um alvo para testes automatizados que afirmam o comportamento específico da Pluggy.

{
      "productName": "Crédito Pessoal Consignado",
      "type": "CREDITO_PESSOAL_COM_CONSIGNACAO",
      "kind": "LOAN",
      "contractAmount": 50000, "currencyCode": "BRL",
      "contractDate": "2022-08-01T00:00:00.000Z", "dueDate": "2028-01-15T00:00:00.000Z",
      "installmentPeriodicity": "MONTHLY", "amortizationScheduled": "SAC", "CET": 0.29,
      "interestRates": [{ "interestRateType": "SIMPLE", "postFixedRate": 0.55, "preFixedRate": 0.6, "referentialRateIndexerSubType": "TJLP" }],
      "installments": { "dueInstallments": 57, "paidInstallments": 73, "pastDueInstallments": 73, "totalNumberOfInstallments": 130632 },
      "payments": { "contractOutstandingBalance": 1000.04 }
    }
 
  // Apenas um tipo/kind de empréstimo é simulado: crédito pessoal consignado. Nenhum financiamento de imóvel, veículo ou empréstimo pessoal sem consignação é representado.

1- Fluxos básicos #

Nota

O fluxo básico também funciona para conectores de Negócios.

Status de execução	Nome de usuário	Descrição
`SUCCESS`	`user-ok`	Conexão bem-sucedida.
`ALREADY_LOGGED_IN`	`user-logged`	O usuário já tem uma sessão de login aberta (precisa sair manualmente).
`ACCOUNT_LOCKED`	`user-locked`	A conta do usuário está bloqueada, precisa de ação manual para ser desbloqueada.
`UNEXPECTED_ERROR`	`user-error`	O conector teve um erro aleatório.
`SITE_NOT_AVAILABLE`	`user-unavailable`	O site do provedor não estava disponível.
`ACCOUNT_NEEDS_ACTION`	`user-account-need-actions`	O provedor está solicitando alguma ação manual do usuário (ou seja, aceitar novos termos de uso).
`ACCOUNT_NEEDS_ACTION` + `providerMessage`	`user-account-need-actions-provider-message`	O provedor está solicitando alguma ação manual do usuário, incluindo instruções para resolver no campo de erro do item `providerMessage`.
`CONNECTION_ERROR`	`user-connection-error`	Houve um erro de conexão interno com o provedor (ou seja, problema de Proxy).
`INVALID_CREDENTIALS`	qualquer outra coisa	As credenciais de usuário/senha eram inválidas.
`PARTIAL_SUCCESS`	`user-ok-account-error`	Erro ao recuperar o produto da conta.
`SUCCESS` com avisos	`user-ok-account-warning`	Aviso no produto da conta.
`ACCOUNT_CREDENTIALS_RESET`	`user-account-credentials-reset`	O usuário precisa atualizar algumas de suas credenciais na instituição.
`USER_NOT_SUPPORTED`	`user-not-supported`	O usuário não está autorizado a realizar login na instituição através da Pluggy.
`SUCCESS` com dados de duas contas correntes	`user-ok-two-checking-accounts`	Sucesso, mas retorna um exemplo de duas contas correntes.

Ampliar dados de resultado #

Nos casos em que é necessário testar grandes quantidades de transações no resultado, você pode usar o nome de usuário user-ok-perf ou user-ok-perf-XXx para recriar essa situação. XX representa o multiplicador para o número de transações a serem recuperadas. Por exemplo, se você escolher 1000 como XX, o nome de usuário resultante seria user-ok-perf-1000x, a fim de multiplicar o resultado por esse número.

O limite desse multiplicador é 5000, então se você usar um número maior, o multiplicador será apenas 5000.

Fluxo Básico | Status de Autorização Pendente (fluxo da Caixa)#

Este é um caso especial que emula o fluxo da Caixa. Consiste em três possíveis status de execução a serem retornados.

Quando um usuário se conecta pela primeira vez, a execução esperada retornada será para confirmar o dispositivo do usuário mostrado (ou seja, "1234-5678").

Assim, a primeira execução (após o usuário confirmar o dispositivo do lado dele) retornará USER_AUTHORIZATION_PENDING e uma mensagem que informa o tempo que o usuário deve esperar até que a autorização seja concedida pela Caixa.

Uma vez que esta etapa é concluída, existem dois cenários possíveis:

Se o usuário atualizar o item dentro do tempo a ser aguardado, o resultado da execução será USER_AUTHORIZATION_NOT_GRANTED e uma mensagem para lembrar o tempo a ser aguardado até que a autorização seja concedida pela Caixa (no caso do Sandbox, o tempo é de 2 minutos).
Se o usuário atualizar o item após o tempo de espera, os dados da conta serão recuperados com sucesso e o relatório de execução será SUCCESS.

Veja a tabela abaixo para mais detalhes:

Status de execução	Nome de usuário	Descrição
`USER_AUTHORIZATION_PENDING`	`user-ok-auth-pending`	Isso reportará um status `USER_AUTHORIZATION_PENDING`, e uma mensagem para esperar 2 minutos até que a instituição conceda autorização. Então, você pode atualizar o item para recuperar os dados após esses 2 minutos, ou obter uma mensagem de autorização ainda não concedida (por favor, leia as próximas linhas).
`USER_AUTHORIZATION_NOT_GRANTED`	reutilizar credenciais (atualizar)	Se o item for atualizado antes que a instituição conceda autorização, o status reportado será `USER_AUTHORIZATION_NOT_GRANTED` e você será solicitado a esperar novamente os 2 minutos após a primeira execução.
`SUCCESS`	reutilizar credenciais (atualizar)	Se o item for atualizado uma vez que a autorização da instituição for concluída, então os dados devem ser recuperados e o relatório de status será `SUCCESS`.

3- MFA 1 etapa #

Cenário	Nome de usuário	MFA	Descrição
Login Ok	`user-ok`	`123456`	Conexão bem-sucedida.
`INVALID_CREDENTIALS_MFA`	`user-ok`	≠ `123456`	O parâmetro MFA fornecido estava incorreto.

4- MFA 2 etapas #

Cenário	Nome de usuário	MFA	Descrição
Login Ok	`user-ok`	`123456`	Conexão bem-sucedida.
`INVALID_CREDENTIALS_MFA`	`user-ok`	≠ `123456`	O parâmetro MFA fornecido estava incorreto.
Login Ok (MFA com imagem QR)	`user-ok-img`	`123456`	Conexão bem-sucedida.
`INVALID_CREDENTIALS_MFA` (MFA com imagem QR)	`user-ok-img`	≠ `123456`	O parâmetro MFA fornecido estava incorreto.
Login Ok (MFA com opções para selecionar)	`user-ok-select`	qualquer	Conexão bem-sucedida.
Login OK (com seleção de telefone antes do MFA)	`user-ok-phone`	`123456`	Conexão bem-sucedida.
`INVALID_CREDENTIALS_MFA` (com seleção de telefone antes do MFA)	`user-ok-phone`	≠ `123456`	O parâmetro MFA fornecido estava incorreto.
Login Ok (com seleção de empresa após o MFA)	`user-ok-multi-company`	`123456`	Conexão bem-sucedida.
`INVALID_CREDENTIALS_MFA`	`user-ok-multi-company`	≠ `123456`	O parâmetro MFA fornecido estava incorreto.
`UNEXPECTED_ERROR`	`user-ok-mfa-error`	`123456`	O conector teve um erro aleatório.
`ACCOUNT_LOCKED`	`user-ok-mfa-locked`	`123456`	A conta do usuário está bloqueada, precisa de ação manual para ser desbloqueada.
`SITE_NOT_AVAILABLE`	`user-ok-mfa-unavailable`	`123456`	O site do provedor não estava disponível.
`CONNECTION_ERROR`	`user-ok-mfa-connection-error`	`123456`	Houve um erro de conexão interno com o provedor (ou seja, problema de Proxy).
`ALREADY_LOGGED_IN`	`user-ok-mfa-logged`	`123456`	O usuário já tem uma sessão de login aberta (precisa sair manualmente).
`ACCOUNT_NEEDS_ACTION`	`user-ok-mfa-account-need-actions`	`123456`	O provedor está solicitando alguma ação manual do usuário (ou seja, aceitar novos termos de uso).

5- Contas Conjuntas (fluxo Bradesco Conta Conjunta)#

Este é um caso especial que emula o fluxo da Bradesco Conta Conjunta.

Abaixo você encontrará dois exemplos:

Testando no widget Pluggy Connect
Testando via Postman

Ao usar o widget Pluggy Connect, o usuário será apresentado para escolher primeiro entre uma "Conta única" ou uma "Conta conjunta".

Se o usuário selecionar "Conta única", será solicitado a fornecer credenciais bancárias e MFA no mesmo passo das credenciais.
Se o usuário selecionar "Conta conjunta", será solicitado apenas as credenciais bancárias. Em seguida, será perguntado qual conta deseja conectar, e depois disso, o MFA será necessário. Se o MFA estiver correto, a conta será conectada com sucesso.

2- Testando via Postman #

Ao testar "conta única", a solicitação é a mesma que a do sandbox MFA 1 etapa. As credenciais bancárias e o MFA são enviados juntos.
Ao testar "conta conjunta", você deve incluir um parâmetro MFA 1 etapa, com o valor simulado: 000000.

Note que isso é o mesmo que o fluxo do widget Connect. Quando o usuário seleciona o fluxo "conta conjunta", a interface não está pedindo para completar o parâmetro MFA.

Este é um caso que originalmente simula um fluxo semelhante ao QR do Inter. Nenhuma credencial é necessária. Uma vez iniciado, o item entrará em um status WAITING_USER_ACTION e retornará um código QR para o usuário escanear.

Este fluxo simulará um código QR em rápida mudança por 10 segundos e, em seguida, simulará o usuário lendo o QR e avançando o estado para um fluxo de login normal.

7- Fluxo de Open Finance #

Para se conectar usando nossa conexão sandbox (veja Criando um item de Open Finance), você precisará enviar um CPF:

Cenário	CPF
Fluxo básico	761.092.776-73
Fluxo de autorização múltipla - aprovado	238.242.640-30
Fluxo de autorização múltipla - rejeitado	051.177.670-55
Fluxo básico - com autenticação lenta	002.502.737-99
Fluxo básico - forçar erro ao obter recursos de OF	163.511.711-99

Isso o redirecionará para a página de login do banco simulado. Por favor, use as seguintes credenciais:

Usuário: ralph.bragg@gmail.com
Senha: P@ssword01

Como funciona o fluxo de autorização múltipla (múltipla alçada)?#

Este fluxo simula um cenário onde, para recuperar os dados da conta, o item deve ser aprovado por outra pessoa (tipicamente outro associado da empresa). Para testar esse cenário, siga estas etapas:

Crie um item sandbox usando um dos CPFs listados na tabela acima. O item não retornará contas imediatamente. Em vez disso, o campo statusDetail indicará que as contas requerem autorização.
Atualize esse item. Dependendo do CPF que você forneceu, as contas podem ou não ser retornadas.