# Subcontas — visão geral

Subcontas permitem que a sua plataforma abra contas de pagamento para os seus sellers, com saldo, extrato e saque próprios, e receba parte de cada transação via split.

## Fluxo de onboarding

1. `POST /v1/proposals` com os dados do seller (PF ou PJ). Retorna `formId`.
2. Acompanhe por `GET /v1/proposals/:formId` ou pelos webhooks `onboarding.*`.
3. A conta é aprovada e o **número da conta chega no webhook `onboarding.create`**, em `data.account`.
4. A partir daí, opere pela subconta usando o header `X-Sub-Account: {numero}`.

Scopes: `proposals/write` para criar, `subaccounts/read` para consultar.

## Rotas

| Método | Path | Função |
|---|---|---|
| POST | `/v1/proposals` | Cria a proposta (PF ou PJ; campos diferentes) |
| GET | `/v1/proposals/:formId` | Status da proposta |
| GET | `/v1/accounts/subaccounts` | Lista subcontas. Filtros: `dateFrom`, `dateTo`, `page`, `perPage` |
| GET | `/v1/charges` | Cobranças da conta |
| GET | `/v1/wallet/balance?accountId=` | Saldo da subconta |

## Regras do cadastro

- **Não reutilize e-mail ou telefone da conta master.** Cada subconta precisa de contato próprio.
- `financialDetails` (PF) e `financialOwnerDetails` (PJ) são obrigatórios e usam códigos — veja [Dados financeiros](./subcontas-financial-details.md).
- O documento define o tipo: CPF (11 dígitos) para PF, CNPJ (14) para PJ.

## Operando pela subconta

O header `X-Sub-Account` faz a requisição valer para a subconta:

```http
POST /v1/charges/pix
Authorization: Bearer {token}
X-Sub-Account: 896532569
Content-Type: application/json

{ "amount": 50.00 }
```

A cobrança nasce na subconta. Para reter uma parte na master, acrescente o array `split` sem `accountNumber` — veja [Split de pagamento](./comece-aqui/split-pagamento.md).

## Saldo, extrato e saque

- Saldo: `GET /v1/wallet/balance?accountId={numero}`
- Extrato: `GET /v1/wallet/transactions?accountId={numero}`
- Saque: `POST /v1/wallet/withdraw` com `accountId`, `amount`, `pixKey` e `pixKeyType`

O saque exige mesma titularidade da conta.

## Eventos

Veja [Subcontas — eventos](./subcontas-eventos.md).