Sandbox
Using our production environment you can access Live and Sandbox connectors. For testing purposes, you can experiment with your integration using our Sandbox connector (which represents our Sandbox environment). This will let you see how the transactions update daily and test all the possible valid connections and erroneous flows.
WarningAll the sandbox items that are not updated for more than 30 days will be deleted without any possibility to get in the future
You will find different flows:
1- Basic flow (we also include special Caixa flow)
2- Basic flow Business
3- MFA 1-step
4- MFA 2-step
5- Joint accounts (Bradesco Conta Conjunta flow)
6- QR Login flow
7- Open Finance flow
For a successful flow, the credentials are:
- Correct password:
password-ok - Correct MFA Token:
123456
Sandbox response structure
The Sandbox (Pluggy Bank connector) returns synthetic data, but with the same field structure as production responses. Below is the field mapping observed in /accounts , /transactions , /investments , and /loans for a test item queried.
// Always returns at least 1 BANK/CHECKING_ACCOUNT and 1 CREDIT/CREDIT_CARD account:
{
"type": "BANK", "subtype": "CHECKING_ACCOUNT",
"balance": 21544.6, "currencyCode": "BRL",
"marketingName": "GOLD Conta Corrente", "taxNumber": "416.799.495-00", "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 that bankData/creditData are mutually exclusive depending on the account's type - the Sandbox even simulates reservedBalances ("piggy banks") inside bankData, which isn't trivial to find documented elsewhere.// Simple transaction (recurring, no extra metadata) — salary, recurring debits:
{ "description": "SALARIO EMPRESA XYZ LTDA", "amount": 8500, "type": "CREDIT", "category": "Salary", "categoryId": "01010000", "paymentData": null,
"creditCardMetadata": null }
// Bank slip (boleto) payment — the only record with paymentData populated:
{
"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" }
}
}
// Installment credit card purchase — the only record with creditCardMetadata populated:
{
"description": "NETFLIX.COM", "amount": -55.9,
"creditCardMetadata": { "installmentNumber": 2, "totalInstallments": 6, "totalAmount": -335.4, "payeeMCC": 5812, "billId":
"3b3341e4-d30c-48d6-bcbe-79a3fe47d704" }
}
// In other words: the Sandbox simulates bank-slip (boleto) payments and installment card purchases, but the checking account queried here has no Pix, TED, or inter-account transfers — all 17 checking-account transactions are: boleto payment, recurring debits (telecom, electricity, condo fees), salary, and bill payment. On the credit card, all 9 transactions are purchases (subscriptions/gym), with no dispute, refund, or cash-advance examples.// 8 investments across 6 type/subtype combinations:
// SECURITY/PGBL — pension plan
{
"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 — pension plan issued by Pluggy itself
{
"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 — appears twice (Premium/Basic)
{
"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 — fixed-income bond
{
"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 — appears twice: one active, one fully withdrawn
{
"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"
}
// No SECURITY/individual-stock example (equity held outside a fund), and nothing explicitly
// labeled Treasury Direct — the closest analog available is the FIXED_INCOME/CDB above.{
"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 }
}
// Only one loan type/kind is simulated: payroll-deductible personal credit. No mortgage, vehicle financing, or unsecured personal loan without consignação is represented.
This is sample dataThe values above are illustrative examples of what the Sandbox can return - they exist to help you build against the right field structure. The Sandbox is not intended to be used as a target for automated tests that assert on Pluggy's specific behavior.
1- Basic flows
| Execution status | User name | Description |
|---|---|---|
| SUCCESS | user-ok | Successful connection. |
| ALREADY_LOGGED_IN | user-logged | The user already has an opened login session (needs to manually log out). |
| ACCOUNT_LOCKED | user-locked | User account is locked, needs manual action to be unlocked. |
| UNEXPECTED_ERROR | user-error | Connector had a random error. |
| SITE_NOT_AVAILABLE | user-unavailable | Provider site was not available. |
| ACCOUNT_NEEDS_ACTION | user-account-need-actions | Provider is requesting some manual action from the user (ie. accept new terms of use). |
ACCOUNT_NEEDS_ACTION + providerMessage | user-account-need-actions-provider-message | Provider is requesting some manual action from the user, including instructions to address it in the item error providerMessage field. |
| CONNECTION_ERROR | user-connection-error | There was an internal connection error with the provider (ie. Proxy issue). |
| INVALID_CREDENTIALS | anything else | The user/password credentials were invalid. |
| PARTIAL_SUCCESS | user-ok-account-error | Error recovering account product. |
| SUCCESS with warnings | user-ok-account-warning | Warning in account product. |
| ACCOUNT_CREDENTIALS_RESET | user-account-credentials-reset | The user needs to update some of their credentials in the institution |
| USER_NOT_SUPPORTED | user-not-supported | The user is not allowed to perform login in the institution though Pluggy. |
| SUCCESS with TWO CHECKING ACCOUNTS data | user-ok-two-checking-accounts | Success, but returns example of two checking accounts |
Enlarge result data
In cases in which is necessary test large amounts of transactions in the result, you can use the user-ok-perf or user-ok-perf-XXx username to recreate this situation. XX represents the multiplier for the number of transactions to be retrieved. For example, if you choose 1000 as XX, the resulting username would be user-ok-perf-1000x, in order to multiply the result by this number.
The limit of this multiplier is 5000, so if you use a larger number, the multiplier will be just 5000.
Basic Flow | Authorization Pending status (Caixa flow)
This is a special case that emulates Caixa flow. It consists of three possible execution statuses to be returned.
When a user connects for the first time, the expected execution returned will be to confirm the user device shown (i.e. "1234-5678").
So, the first execution (after the user confirms the device on his side) will return USER_AUTHORIZATION_PENDING and a message that informs the time that the user must be awaited until authorization is granted from Caixa.
Once this step is completed, there are two possible scenarios:
1- If the user updates the item within the time to be awaited, the execution result will be USER_AUTHORIZATION_NOT_GRANTED and a message to remind the time to be awaited until the authorization is granted from Caixa (in Sandbox case, the time is 2 minutes).
2- If the user updates the item after the wait is over, the data of the account will be retrieved successfully and the execution report will be SUCCESS.
| Execution status | User name | Description |
|---|---|---|
| USER_AUTHORIZATION_PENDING | user-ok-auth-pending | This will report a USER_AUTHORIZATION_PENDING status. And a message to wait for 2 minutes until institution grant authorization. Then, you can update the item to retrieve the data after those 2 minutes or get a not yet granted authorization message (please read nexts rows). |
| USER_AUTHORIZATION_NOT_GRANTED | re-use credentials (update) | If the item is updated before institution grant authorization, the status reported will be USER_AUTHORIZATION_NOT_GRANTED and will be newly asked to wait for the 2 minutes after first execution. |
| SUCCESS | re-use credentials (update) | If the item is updated once the institution authorization is completed, then the data should be retrieved and the status report will be SUCCESS. |
3- MFA 1-step
| Scenario | User name | MFA | Description |
|---|---|---|---|
| Login Ok | user-ok | 123456 | Successful connection. |
| INVALID_CREDENTIALS_MFA | user-ok | ≠ 123456 | The MFA parameter provided was incorrect. |
4- MFA 2-step
| Scenario | User name | MFA | Description |
|---|---|---|---|
| Login Ok | user-ok | 123456 | Successful connection. |
| INVALID_CREDENTIALS_MFA | user-ok | ≠ 123456 | The MFA parameter provided was incorrect. |
| Login Ok (MFA with QR image) | user-ok-img | 123456 | Successful connection. |
| INVALID_CREDENTIALS_MFA (MFA with QR image) | user-ok-img | ≠ 123456 | The MFA parameter provided was incorrect. |
| Login Ok (MFA with options to select) | user-ok-select | any | Successful connection. |
| Login OK (with phone selection before MFA) | user-ok-phone | 123456 | Successful connection. |
| INVALID_CREDENTIALS_MFA (with phone selection before MFA) | user-ok-phone | ≠ 123456 | The MFA parameter provided was incorrect. |
| Login Ok (with company selection after MFA) | user-ok-multi-company | 123456 | Successful connection. |
| INVALID_CREDENTIALS_MFA | user-ok-multi-company | ≠ 123456 | The MFA parameter provided was incorrect. |
| UNEXPECTED_ERROR | user-ok-mfa-error | 123456 | Connector had a random error. |
| ACCOUNT_LOCKED | user-ok-mfa-locked | 123456 | User account is locked, needs manual action to be unlocked. |
| SITE_NOT_AVAILABLE | user-ok-mfa-unavailable | 123456 | Provider site was not available. |
| CONNECTION_ERROR | user-ok-mfa-connection-error | 123456 | There was an internal connection error with the provider (ie. Proxy issue). |
| ALREADY_LOGGED_IN | user-ok-mfa-logged | 123456 | The user already has an opened login session (needs to manually log out). |
| ACCOUNT_NEEDS_ACTION | user-ok-mfa-account-need-actions | 123456 | Provider is requesting some manual action from the user (ie. accept new terms of use). |
5- Joint Accounts (Bradesco Conta Conjunta flow)
This is a special case that emulates Bradesco Conta Conjunta flow.
**
Below you will find two examples:**
1- Testing in Pluggy Connect widget
2- Testing via Postman
1- Testing in Pluggy Connect widget
When using the widget, the user will be presented to choose first from either a "Single account" or a "Joint account".

- If the user selects "Single account" it will be asked for bank credentials and MFA in the same step as the credentials.

- If the user selects "Joint account", it will be asked only for bank credentials. Then, it will be asked which account wants to connect, and after that, the MFA will be required. If the MFA is correct, the account will connect successfully.




2-Testing via Postman
- When testing "single account" the request is the same as sandbox MFA 1-step. The bank credentials and mfa are sent together.
- When testing "joint account", you have to include an MFA 1-step parameter, with the mock value: '000000'.
Note that this is the same as the Connect widget flow. When the user selects the "joint account" flow, the UI is not asking to complete the MFA parameter.
6- QR Login flow
This is a case that originally simulates a flow similar to Inter QR. No credentials are necessary. Once started, the item will enter a WAITING_USER_ACTION status, and return a QR code for the user to scan.
This flow will simulate a rapidly changing QR code for 10 seconds and then simulate the user reading the QR and advancing the state to a normal login flow.
7 - Open Finance flow
To connect using our sandbox connection, you will be required to send a CPF:
| Scenario | CPF |
|---|---|
| Basic flow | 761.092.776-73 |
| Multiple authorization flow - approved | 238.242.640-30 |
| Multiple authorization flow - rejected | 051.177.670-55 |
| Basic flow - with slow authentication | 002.502.737-99 |
| Basic flow - force error getting OF resources | 163.511.711-99 |
This will redirect you to the mock bank login page. Please use the following credentials:
- User:
[email protected] - Password:
P@ssword01
How does the multiple authorization (multipla alçada) flow work?
This flow simulates a scenario where, in order to retrieve account data, the item must be approved by another person (typically another company associate). To test this scenario, follow these steps:
1- Create a sandbox item using one of the CPFs listed in the table above. The item will not return accounts immediately. Instead, the statusDetail field will indicate that the accounts require authorization.
2- Update that item. Depending on the CPF you provided, the accounts may or may not be returned.
Updated 2 days ago
