> ## 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.

# Consultar subconta

> Devolve os dados cadastrais, o status de credenciamento e as métricas de uma subconta da sua conta master.

Esta rota mostra a situação atual de uma subconta (SubMerchant) específica: dados da empresa, status no credenciamento, datas de aprovação ou inativação e métricas de volume e split. É a forma de confirmar, a qualquer momento, se um vendedor já pode transacionar.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Saber se a subconta já foi aprovada | Confira se `status` é `active` |
| Confirmar um aviso de status recebido | Consulte depois de receber a notificação e decida pelo `status` da resposta |
| Mostrar ao vendedor o volume processado | Use o bloco `metrics` |
| Exibir os dados cadastrais no seu sistema | Use os campos da empresa |
| Ver várias subcontas de uma vez | Use [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md) |

## Antes de chamar

* Tenha o `id` da subconta, devolvido em [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md) ou em [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md).
* Autentique com a chave secreta (`sk_`) da **conta master** à qual a subconta está ligada ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).

## Parâmetros de caminho

**id** `string` *required*

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

## Respostas

**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.: `2026-10-21T14: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.

**propriedades**

**totalVolume** `number`

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

**splitBalance** `number`

Total recebido pela subconta via split, em reais. Ex.: `450` (R\$ 450,00).

**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.: `Roupas e acessórios femininos`.

**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.: `2026-10-20T18:45:52.988Z`.

**totalSales** `number`

Total de vendas da subconta. Ex.: `0`.

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

### O que fazer em cada status

| Status | Próximo passo |
| - | - |
| `pending` | Cadastro em análise. Confira se todos os documentos foram enviados |
| `correcting` | A Finvia pediu correção de dados ou documentos. Corrija no painel, na gestão de subcontas. Depois do reenvio, 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 |
| `active` | Aprovada. Busque as [chaves de API](https://docs.fastpaybrasil.com/referencia/fast-connect/chaves-de-api.md) da subconta e libere as vendas |
| `rejected` | Reprovada. Veja os motivos comuns em [Regras de credenciamento](https://docs.fastpaybrasil.com/guias/fast-connect/regras-de-credenciamento.md) |
| `blocked` | Bloqueada |
| `inactive` | Inativada |

O motivo de uma recusa ou de um pedido de correção chega no campo `rejectionReason` do aviso de status, descrito em [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md). Esta rota não devolve esse campo.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Subconta encontrada | Objeto da subconta |
| `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:** antes de liberar um vendedor para vender na sua plataforma, confira se o status é `active`. Uma subconta que ainda não foi aprovada não está apta a transacionar.

## 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 |
| Status parado em `correcting` | Correções pedidas e ainda não feitas | Corrija os dados ou reenvie os documentos pedidos |

```http REST (JSON) theme={null}
GET /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo" \
  -u "$FINVIA_API_KEY:"
```

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

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

const submerchant = await response.json();

if (submerchant.status === 'active') {
  // liberar vendas e buscar as chaves da subconta
}
```

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

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    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/36OO3bcGjhPjjF3tzrqOGcmQuKo');

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/36OO3bcGjhPjjF3tzrqOGcmQuKo"))
            .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/36OO3bcGjhPjjF3tzrqOGcmQuKo");

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/36OO3bcGjhPjjF3tzrqOGcmQuKo", 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/36OO3bcGjhPjjF3tzrqOGcmQuKo")
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}
{
  "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "tradeName": "Loja Exemplo",
  "legalName": "LOJA EXEMPLO LTDA",
  "companyTaxId": "11222333000181",
  "averageMonthlyRevenue": 30000,
  "averageOrderValue": 150,
  "productType": "physical",
  "website": "https://loja.exemplo.com.br",
  "gatewayId": "36O08tjxJCxtEFApVPyWbryktP3",
  "approvedAt": "2026-10-21T14:02:51.762Z",
  "inactivatedAt": null,
  "status": "active",
  "metrics": {
    "totalVolume": 15000,
    "splitBalance": 450,
    "splitRate": 3
  },
  "contactEmail": "contato@lojaexemplo.com.br",
  "productDescription": "Roupas e acessórios femininos",
  "softDescriptor": null,
  "createdAt": "2026-10-20T18:45:52.988Z",
  "totalSales": 0
}
```

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

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

## Veja também

> [card] [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md)
>
> Todas as subcontas, com filtros.

> [card] [Chaves de API da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/chaves-de-api.md)
>
> Chaves para cobrar em nome do vendedor.

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

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


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