> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar subcontas

> Lista as subcontas vinculadas à sua conta master, com filtros por status, busca, CNPJ, período de criação e conta bancária.

Esta rota devolve todas as subcontas (SubMerchants) ligadas à sua conta master (MerchantMaster) no [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md). É a visão de carteira do marketplace: quem está ativo, quem ainda está em análise, quem foi bloqueado e quanto cada subconta já movimentou.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Montar a tela de gestão de vendedores no seu sistema | Liste sem filtros e pagine com `page` e `size` |
| Acompanhar a fila de credenciamento | Filtre por `status=pending&status=correcting` |
| Encontrar uma subconta pelo CNPJ, nome ou e-mail | Use `search`, ou `companyTaxId` só com dígitos |
| Ver quem entrou em um período | Use `createdFrom` e `createdTo` |
| Achar vendedores sem conta bancária ativa | Filtre por `completeness=incomplete` |
| Ver os dados de uma única subconta já conhecida | Use [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md) |

## Antes de chamar

* O módulo Connect precisa estar habilitado pela Finvia na sua conta master. Sem isso, a resposta é `403`.
* Autentique com a chave secreta (`sk_`) da **conta master**. A lista sempre se restringe às subcontas ligadas a ela ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).

## Parâmetros de consulta

Todos os parâmetros são opcionais. Sem `orderBy`, a lista vem da subconta mais recente para a mais antiga.

**status** `string[]`

Filtra pelo status atual da subconta. Valores aceitos: `active`, `inactive`, `pending`, `pre_approved`, `correcting`, `rejected` e `blocked`. Qualquer outro valor devolve `400`. Para mais de um status, **repita o parâmetro**: `?status=pending&status=correcting`. Não use lista separada por vírgula: `?status=pending,correcting` não dá erro, mas devolve a lista vazia.

**search** `string`

Busca por trecho, sem diferenciar maiúsculas de minúsculas, na razão social, no nome fantasia, no e-mail de contato e no CNPJ (com ou sem máscara). Ex.: `loja exemplo`.

**companyTaxId** `string`

CNPJ exato da subconta, **somente dígitos**. Com máscara, não encontra nada. Ex.: `11222333000181`.

**legalName** `string`

Trecho da razão social. Diferencia maiúsculas de minúsculas. Ex.: `LOJA EXEMPLO`.

**tradeName** `string`

Trecho do nome fantasia. Diferencia maiúsculas de minúsculas. Ex.: `Loja Exemplo`.

**createdFrom** `string`

Data inicial de criação, no formato `AAAA-MM-DD`. Inclusiva, considerando o dia no fuso de São Paulo. Ex.: `2026-10-01`.

**createdTo** `string`

Data final de criação, no formato `AAAA-MM-DD`. Inclusiva, considerando o dia no fuso de São Paulo. Ex.: `2026-10-31`.

**completeness** `string`

`complete` traz as subcontas com conta bancária ativa; `incomplete`, as que não têm.

**currency** `string`

Não filtra subcontas. Limita à moeda informada as somas `totalSales` e `totalSplit` de cada item. Ex.: `BRL`.

**page** `integer` (default: 1)

Número da página, começando em `1`.

**size** `integer` (default: 10)

Quantidade de subcontas por página. Ex.: `20`.

**orderBy** `string`

Campos de ordenação com o **nome da coluna em snake\_case**, separados por vírgula. Use o prefixo `-` para ordem decrescente. Ex.: `legal_name,-created_at` (razão social em ordem crescente e, em caso de empate, as mais recentes primeiro). Nomes em camelCase, como `legalName`, geram erro `500`.

**createdAt** `string` *deprecated*

**Legado.** Compara igualdade exata com o momento da criação e, na prática, quase nunca encontra nada. Use `createdFrom` e `createdTo`.

> [!NOTE]
>
> Os filtros `updatedAt`, `approvedAt`, `rejectedAt`, `blockedAt` e `inactivatedAt` também são **legados**: comparam igualdade exata com o momento do evento e quase nunca encontram resultado. Não use.

> [!TIP]
>
> **Para o desenvolvedor:** para varrer toda a carteira, percorra as páginas até `page` ser igual a `pages`. Mais detalhes em [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md).

## Respostas

**data** `object[]`

Subcontas da página atual.

**propriedades**

**id** `string`

Identificador único da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`.

**tradeName** `string`

Nome fantasia. Ex.: `Loja Exemplo`.

**legalName** `string`

Razão social. Ex.: `LOJA EXEMPLO LTDA`.

**companyTaxId** `string`

CNPJ, só com dígitos. Ex.: `11222333000181`.

**averageMonthlyRevenue** `number`

Faturamento médio mensal informado no cadastro. O contrato descreve o campo como "decimal as string", mas o tipo declarado é `number`. Ex.: `5000`.

**averageOrderValue** `number`

Ticket médio informado no cadastro. O contrato descreve o campo como "decimal as string", mas o tipo declarado é `number`. Ex.: `100`.

**productType** `string`

Tipo de produto vendido: `digital`, `physical` ou `both`.

**website** `string`

Site da subconta (formato `uri`). Ex.: `https://loja.exemplo.com.br`.

**gatewayId** `string`

Identificador do gateway ligado à subconta. Ex.: `36O08tjxJCxtEFApVPyWbryktP3`.

**approvedAt** `string | null`

Data e hora da aprovação (formato `date-time`). Ex.: `2025-12-04T20:02:51.762Z`.

**inactivatedAt** `string | null`

Data e hora da inativação (formato `date-time`). Ex.: `null`.

**status** `string`

Status atual: `active`, `pending`, `pre_approved`, `correcting`, `inactive`, `rejected` ou `blocked`.

**metrics** `object`

Métricas agregadas da subconta. A descrição no contrato diz que o objeto é devolvido por `GET /v1/submerchants/{id}`.

**propriedades**

**totalVolume** `number`

Volume total de cobranças da subconta (soma dos valores), em reais. Ex.: `15000`.

**splitBalance** `number`

Total recebido pela subconta via split, em reais. Ex.: `450`.

**splitRate** `number`

Percentual médio de split aplicado à subconta. Ex.: `3`.

**contactEmail** `string`

E-mail de contato (formato `email`). Ex.: `contato@lojaexemplo.com.br`.

**productDescription** `string`

Descrição dos produtos ou serviços. Ex.: `Venda de acessórios para celular.`

**softDescriptor** `string | null`

Nome que aparece na fatura do cartão do cliente. Ex.: `null`.

**createdAt** `string`

Data e hora de criação (formato `date-time`). Ex.: `2025-12-04T18:45:52.988Z`.

**hasBankAccount** `boolean`

Indica se a subconta tem conta bancária ativa. Ex.: `true`.

**totalSales** `number`

Soma das vendas da subconta. Com o parâmetro `currency`, considera só essa moeda. Ex.: `15000`.

**totalSplit** `number`

Soma recebida pela subconta via split. Com o parâmetro `currency`, considera só essa moeda. Ex.: `450`.

**total** `integer`

Total de subcontas em todas as páginas. Ex.: `100`.

**page** `integer`

Página atual. Ex.: `1`.

**size** `integer`

Subcontas por página. Ex.: `10`.

**pages** `integer`

Total de páginas. Ex.: `10`.

> [!NOTE]
>
> O contrato desta rota não informa quais campos da subconta são sempre presentes. Trate qualquer campo como possivelmente ausente.

### Status da subconta

| Status | O que significa para você |
| - | - |
| `pending` | Cadastro recebido, em análise |
| `correcting` | A Finvia pediu correção de dados ou documentos. Só acontece a partir de `pending` ou `pre_approved`. Depois que a correção é reenviada, a subconta volta para a análise |
| `pre_approved` | Documentos obrigatórios conferidos. A subconta está sendo credenciada nas adquirentes e aguarda a aprovação final, que só parte deste status |
| `active` | Aprovada e apta a transacionar |
| `rejected` | Reprovada |
| `blocked` | Bloqueada |
| `inactive` | Inativada |

O ciclo completo e quais mudanças geram aviso estão em [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md).

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Lista devolvida | `data`, `total`, `page`, `size`, `pages` |
| `400` | Valor de filtro inválido (ex.: `status` fora da lista) | `{"statusCode": 400, "message": ["..."], "error": "Bad Request"}` |
| `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` |

> [!NOTE]
>
> **Para o negócio:** com o filtro de `status` e o período de criação, o time de operações acompanha o funil de credenciamento dos vendedores: quantos entraram, quantos estão em correção, quantos foram aprovados. `completeness=incomplete` mostra quem ainda não cadastrou conta bancária. `totalSales` e `totalSplit` mostram o movimento de cada subconta.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401` | Chave ausente, inválida ou mal codificada no Basic | Codifique `chave:` em Base64 (com os dois-pontos no fim) |
| `403` `Fast Connect not enabled.` | Connect não habilitado na conta master | Peça a habilitação à Finvia |
| Lista vazia com vários status | Status enviados separados por vírgula | Repita o parâmetro: `status=pending&status=correcting` |
| Busca por CNPJ não encontra | `companyTaxId` enviado com máscara | Envie só dígitos, ou use `search`, que aceita com ou sem máscara |
| Busca por nome não encontra | `legalName` e `tradeName` diferenciam maiúsculas de minúsculas | Use `search` |
| Filtro por data não traz nada | Foi usado um filtro legado de data exata (`createdAt`, `approvedAt`...) | Use `createdFrom` e `createdTo` |
| `500` ao ordenar | `orderBy` com nome em camelCase | Use snake\_case: `legal_name,-created_at` |

```http REST (JSON) theme={null}
GET /v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl -G "https://api-global.fastpaybrasil.com/v1/submerchants" \
  -u "$FINVIA_API_KEY:" \
  --data-urlencode "status=pending" \
  --data-urlencode "status=correcting" \
  --data-urlencode "createdFrom=2026-10-01" \
  --data-urlencode "createdTo=2026-10-31" \
  --data-urlencode "page=1" \
  --data-urlencode "size=20" \
  --data-urlencode "orderBy=legal_name,-created_at"
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const params = new URLSearchParams([
  ['status', 'pending'],
  ['status', 'correcting'], // repita o parâmetro para vários status
  ['createdFrom', '2026-10-01'],
  ['createdTo', '2026-10-31'],
  ['page', '1'],
  ['size', '20'],
  ['orderBy', 'legal_name,-created_at'],
]);

const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants?${params}`, {
  headers: { Authorization: `Basic ${credentials}` },
});

const { data, page, pages } = await response.json();
```

```python Python theme={null}
import os

import requests

params = [
    ("status", "pending"),
    ("status", "correcting"),
    ("createdFrom", "2026-10-01"),
    ("createdTo", "2026-10-31"),
    ("page", "1"),
    ("size", "20"),
    ("orderBy", "legal_name,-created_at"),
]

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/submerchants",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    params=params,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&createdFrom=2026-10-01&createdTo=2026-10-31&page=1&size=20&orderBy=legal_name,-created_at")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
      "tradeName": "Loja Exemplo",
      "legalName": "LOJA EXEMPLO LTDA",
      "companyTaxId": "11222333000181",
      "averageMonthlyRevenue": 5000,
      "averageOrderValue": 100,
      "productType": "digital",
      "website": "https://loja.exemplo.com.br",
      "gatewayId": "36O08tjxJCxtEFApVPyWbryktP3",
      "approvedAt": null,
      "inactivatedAt": null,
      "status": "pending",
      "metrics": {
        "totalVolume": 0,
        "splitBalance": 0,
        "splitRate": 0
      },
      "contactEmail": "contato@lojaexemplo.com.br",
      "productDescription": "Venda de acessórios para celular.",
      "softDescriptor": null,
      "createdAt": "2026-10-20T18:45:52.988Z",
      "hasBankAccount": true,
      "totalSales": 0,
      "totalSplit": 0
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}
```

```json 401 theme={null}
{ "statusCode": 401, "message": "Unauthorized" }
```

```json 403 theme={null}
{ "statusCode": 403, "message": "Fast Connect not enabled." }
```

## Veja também

> [card] [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md)
>
> Dados e métricas de uma subconta.

> [card] [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md)
>
> Cadastro de um novo vendedor.

> [card] [Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)
>
> Fluxo de cadastro e credenciamento.

> [card] [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md)
>
> Avisos de mudança de status da subconta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.