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

# Subcontas merchant

> Carteiras lógicas sob a conta principal: CRUD, saldo, limites, PIX com subaccountId e pricing.

**Subcontas merchant** são carteiras lógicas vinculadas à sua conta GoatPay principal. Servem para separar saldo por produto, parceiro ou unidade de negócio, sem abrir outra conta na GoatPay.

## Habilitação

| Etapa           | Onde                            | Detalhe                                     |
| --------------- | ------------------------------- | ------------------------------------------- |
| Solicitar       | Dashboard → Contas → Subcontas  | Informe WhatsApp; status em `access-status` |
| Aprovação       | Equipe GoatPay (admin)          | Ativa `merchantSubaccountsEnabled` na conta |
| PIX em subconta | Admin, após habilitar subcontas | Flag `merchantSubaccountsPixEnabled`        |

Sem habilitação, a API retorna **403** em rotas `subaccount/*` e ao enviar `subaccountId` no PIX.

A solicitação de acesso **não** existe na API pública hoje — apenas no [dashboard](https://app.goatpay.com.br).

## Permissões na API key

Marque o grupo **Subcontas** ao criar a chave. Cada rota exige uma permissão:

| Permissão                               | Uso                                                               |
| --------------------------------------- | ----------------------------------------------------------------- |
| `subaccount/create`                     | Criar subconta                                                    |
| `subaccount/get`                        | Consultar por `id` ou `externalReference`                         |
| `subaccount/list`                       | Listar subcontas                                                  |
| `subaccount/update`                     | Renomear ou `ACTIVE` / `DISABLED`                                 |
| `subaccount/delete`                     | Excluir (saldo zerado; retorna `{ id }`)                          |
| `subaccount/balance`                    | Saldo da subconta                                                 |
| `subaccount/add-balance`                | Conta principal → subconta                                        |
| `subaccount/remove-balance`             | Subconta → conta principal                                        |
| `subaccount/transfer`                   | Entre duas subcontas                                              |
| `subaccount/lock` / `subaccount/unlock` | Bloqueio operacional                                              |
| `subaccount/set-limits`                 | Limites diário/mensal/por transação                               |
| `subaccount/set-pricing`                | Acréscimo de taxa PIX entrada/saída (somado à taxa principal)     |
| `subaccount/get`                        | `GET /subaccount/pricing` — preview das taxas com `lines[].label` |

Para PIX na subconta, use também `payment-pix/create` e/ou `transfer-pix/create` na mesma chave.

## Conceitos

| Conceito            | Descrição                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| Conta principal     | Dono do saldo “global”; movimentações `add-balance` / `remove-balance` cruzam main ↔ sub                     |
| `externalReference` | ID do seu sistema (máx. 64). **Obrigatório** na API pública no `create`                                      |
| Trilho              | **Somente Padrão** — movimentações e PIX em subconta usam saldo `*Padrao`; não há parâmetro `pixRail` na API |
| Saldo               | Use `spendablePadrao` (e campos `availablePadrao` / `lockedPadrao` / `pendingPadrao`)                        |
| Limites             | Validados por **soma** de débitos `COMPLETED` no período (sem contador em tabela)                            |
| `lockMode`          | `full`, `withdraw_only`, `deposit_only` — afeta PIX e movimentações                                          |

<h2 id="portal-wallet">
  Portal Wallet
</h2>

O **Portal Wallet** permite que o titular ou operador de uma subconta acesse uma carteira dedicada em [wallet.goatpay.com.br](https://wallet.goatpay.com.br), separada do login da conta principal em [app.goatpay.com.br](https://app.goatpay.com.br).

Cada subconta pode ter **um** usuário de portal (e-mail + senha). A sessão é isolada da conta merchant.

### O que o operador vê

| Recurso                | Descrição                                                     |
| ---------------------- | ------------------------------------------------------------- |
| Dashboard              | Saldo, métricas do dia, gráfico de volume e atividade recente |
| Depositar / Transferir | PIX na subconta (trilho Padrão)                               |
| Extrato e resumo       | Movimentações filtradas pela subconta                         |
| Disputas (MED)         | MEDs vinculados a transações da subconta                      |
| Conta                  | Segurança, 2FA, senha                                         |

### Habilitar login na subconta (API key)

Use a API pública `v1/subaccount/*` com header `X-API-Key`. Todas as rotas abaixo exigem permissões específicas na chave (`subaccount/portal/*`).

#### Na criação da subconta

Inclua `portalEmail` e `portalPassword` em `POST /v1/subaccount/create`:

```bash theme={null}
curl -X POST 'https://api.goatpay.com.br/v1/subaccount/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "personType": "PF",
    "fullName": "Maria Silva",
    "cpf": "52998224725",
    "birthDate": "1990-05-15",
    "postalCode": "01310100",
    "externalReference": "loja-parceiro-a",
    "portalEmail": "operador@empresa.com",
    "portalPassword": "SenhaForte!123"
  }'
```

| Campo            | Tipo   | Obrigatório                    | Descrição                                                                 |
| ---------------- | ------ | ------------------------------ | ------------------------------------------------------------------------- |
| `portalEmail`    | string | Se quiser portal               | E-mail de login no Portal Wallet                                          |
| `portalPassword` | string | Sim, se informar `portalEmail` | Senha inicial (mín. 8 caracteres, maiúscula, minúscula, número e símbolo) |

Se **ambos** forem informados, o acesso fica **ativo na hora**. O operador entra em [wallet.goatpay.com.br/login](https://wallet.goatpay.com.br/login) com e-mail e senha — **sem confirmação por e-mail**.

<Warning>
  Se você informar `portalEmail` sem `portalPassword`, a API retorna erro.
</Warning>

#### Subconta já existente (sem login)

`POST /v1/subaccount/portal/setup` — permissão `subaccount/portal/setup`:

```bash theme={null}
curl -X POST 'https://api.goatpay.com.br/v1/subaccount/portal/setup' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalReference": "loja-parceiro-a",
    "email": "operador@empresa.com",
    "password": "SenhaForte!123"
  }'
```

| Campo                       | Obrigatório       | Descrição                                         |
| --------------------------- | ----------------- | ------------------------------------------------- |
| `id` ou `externalReference` | Sim (um dos dois) | Identifica a subconta                             |
| `email`                     | Sim               | E-mail de login (único na plataforma para portal) |
| `password`                  | Sim               | Senha do operador                                 |

Resposta de sucesso: `{ "success": true, "mode": "portal_ready" }`.

### Consultar status do portal (API key)

`GET /v1/subaccount/portal/status` — permissão `subaccount/portal/get`

* Sem query: lista todas as subcontas com estado do portal.
* Com `?id=` ou `?externalReference=`: status de uma subconta.

Exemplo de item na resposta:

```json theme={null}
{
  "subaccountId": "clx_subconta",
  "subaccountName": "Loja Parceiro",
  "portal": {
    "state": "active",
    "email": "operador@empresa.com",
    "emailVerified": true,
    "twoFactorEnabled": false,
    "lastLoginAt": "2026-06-08T14:22:00.000Z"
  }
}
```

Estados possíveis:

| Estado                 | Significado                                                        |
| ---------------------- | ------------------------------------------------------------------ |
| `none`                 | Sem login de portal configurado                                    |
| `active`               | E-mail e senha cadastrados; operador pode entrar                   |
| `disabled`             | Portal revogado pelo merchant                                      |
| `pending_password`     | Legado — reconfigure com `portal/setup`                            |
| `invite_pending`       | Legado — reconfigure com `portal/setup`                            |
| `pending_verification` | Legado — contas antigas antes da remoção da verificação por e-mail |

### Outras rotas de gestão (API key)

| Método | Rota                                 | Permissão                        | Uso                        |
| ------ | ------------------------------------ | -------------------------------- | -------------------------- |
| `POST` | `/v1/subaccount/portal/update-email` | `subaccount/portal/update-email` | Alterar e-mail do operador |
| `POST` | `/v1/subaccount/portal/revoke`       | `subaccount/portal/revoke`       | Revogar acesso ao portal   |
| `POST` | `/v1/subaccount/portal/reset-2fa`    | `subaccount/portal/reset-2fa`    | Resetar 2FA do operador    |

### Alternativa: dashboard merchant

As mesmas operações estão disponíveis no app em **Contas → Subcontas → Gerenciar subconta → aba Portal**.

### Login do operador (wallet)

O operador entra em [wallet.goatpay.com.br/login](https://wallet.goatpay.com.br/login) com o e-mail e a senha cadastrados pelo merchant. A sessão fica limitada à subconta vinculada — saldo, PIX, extrato e MED respeitam os mesmos limites da API pública.

### Relação com a API pública

* Criar/movimentar subcontas via API key continua em `v1/subaccount/*`.
* O Portal Wallet é **opcional** e voltado a operação humana na interface web.
* PIX, extrato e MED no wallet respeitam os mesmos saldos e bloqueios da subconta no trilho Padrão.

## Fluxo recomendado

<Steps>
  <Step title="1. Habilitar e criar subconta">
    Após aprovação no dashboard, crie a subconta com cadastro KYC (PF ou PJ): `POST /subaccount/create` com nome, CPF, data de nascimento, CEP e, para PJ, CNPJ, razão social, site e comprovante em multipart.

    No app GoatPay, configure **taxas globais** em Subcontas e use **Gerenciar subconta** para saldo, transferências, limites, bloqueios e taxas PIX in/out. Opcionalmente configure o **Portal Wallet** na aba Portal ou com `portalEmail` + `portalPassword` na criação (senha obrigatória junto com o e-mail).

    [Criar subconta](/api-reference/endpoint/subaccount/create) · [Portal Wallet](#portal-wallet)
  </Step>

  <Step title="2. Alocar saldo (opcional)">
    `POST /subaccount/add-balance` transfere da conta principal para a subconta.

    Ou receba PIX direto na subconta (passo 4).
  </Step>

  <Step title="3. Configurar limites e bloqueios (opcional)">
    `set-limits`, `lock` / `unlock` conforme política de risco.
  </Step>

  <Step title="4. PIX na subconta">
    Não há rotas `/subaccount/payment-pix`. Use as rotas PIX normais com **`subaccountId`** no body (veja abaixo).
  </Step>

  <Step title="5. Reconciliar">
    `GET /subaccount/balance` ou `get` / `list`. Extrato filtrado por subconta (API key ou dashboard): `GET /v1/account/transactions?subaccountId={id}` ou `merchantSubaccountId={id}`. Cobranças PIX da subconta: `GET /v1/payment-pix/list?subaccountId={id}`.

    [Extrato da conta](/api-reference/endpoint/account/transactions) · [Listar cobranças PIX](/api-reference/endpoint/payment-pix/list)
  </Step>
</Steps>

## Receber PIX (cobrança QR) na subconta

Não existe `POST /subaccount/payment-pix/create`. Use a rota padrão de cobrança com o ID da subconta:

```bash theme={null}
curl -X POST 'https://api.goatpay.com.br/v1/payment-pix/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 100,
    "description": "Pedido loja A",
    "subaccountId": "clx_subconta",
    "externalReference": "pedido-9001"
  }'
```

| Requisito       | Detalhe                                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Permissão       | `payment-pix/create`                                                                                                                              |
| Flag da conta   | `merchantSubaccountsPixEnabled`                                                                                                                   |
| Subconta        | **`ACTIVE`** obrigatório; `DISABLED` ou excluída (soft delete) não operam PIX. Não bloqueada para depósito (`lockMode` ≠ `full` / `deposit_only`) |
| Liquidação      | O **líquido** credita o saldo da subconta                                                                                                         |
| Lucro (pricing) | Diferença entre taxa cobrada e taxa da subconta pode ir para a conta principal (`SUBACCOUNT_PROFIT`)                                              |

Consulta e listagem: [Consultar cobrança](/api-reference/endpoint/payment-pix/get) (por `id` ou `externalReference`); [Listar](/api-reference/endpoint/payment-pix/list) com `?subaccountId=` para filtrar só aquela subconta. A resposta inclui `subaccountId` quando a cobrança foi criada com subconta. Webhooks `payment.created` / `payment.paid` não mudam.

[Documentação completa de criar cobrança PIX](/api-reference/endpoint/payment-pix/create)

## Enviar PIX (saque) da subconta

Mesmo padrão: rota de saque existente + `subaccountId`:

```bash theme={null}
curl -X POST 'https://api.goatpay.com.br/v1/transfer-pix/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 50,
    "description": "Repasse fornecedor",
    "pixKey": "12345678909",
    "pixKeyType": "CPF",
    "subaccountId": "clx_subconta",
    "coverFee": true
  }'
```

| Requisito     | Detalhe                                                         |
| ------------- | --------------------------------------------------------------- |
| Permissão     | `transfer-pix/create` (ou alias `payouts/create`)               |
| Flag da conta | `merchantSubaccountsPixEnabled`                                 |
| Saldo         | Débito no saldo **spendable** da subconta no trilho da operação |
| Bloqueio      | `withdraw_only` ou `full` impedem saque                         |
| Limites       | `dailyLimit`, `monthlyLimit`, `perTransactionLimit` da subconta |

[Documentação de enviar PIX](/api-reference/endpoint/transfer-pix/create)

## Movimentação interna (sem PIX)

| Operação        | Rota                              | Efeito                              |
| --------------- | --------------------------------- | ----------------------------------- |
| Principal → sub | `POST /subaccount/add-balance`    | Débito na main, crédito na sub      |
| Sub → principal | `POST /subaccount/remove-balance` | Débito na sub, crédito na main      |
| Sub → sub       | `POST /subaccount/transfer`       | Entre duas subcontas da mesma conta |

Rotas `add-balance`, `remove-balance` e `transfer` são **idempotentes** quando você repete o mesmo `externalReference` (ou payload equivalente derivado internamente).

## Saldo da subconta

`GET /subaccount/balance?id=...` ou `?externalReference=...`

Exemplo de `balance` em `GET /subaccount/get/:id`:

```json theme={null}
{
  "availablePadrao": 500,
  "pendingPadrao": 0,
  "lockedPadrao": 0,
  "spendablePadrao": 500
}
```

Na **API pública**, `balance` expõe apenas campos `*Padrao`. Use `spendablePadrao` como saldo utilizável para saques e `remove-balance`. Exclusão (`delete`) exige saldo **Padr?o** zerado.

## Extrato filtrado

`GET /v1/account/transactions?subaccountId={id}` inclui, entre outros:

| Tipo                        | Origem                               |
| --------------------------- | ------------------------------------ |
| `SUBACCOUNT_ADD_BALANCE`    | `add-balance`                        |
| `SUBACCOUNT_REMOVE_BALANCE` | `remove-balance`                     |
| `SUBACCOUNT_TRANSFER`       | `transfer` entre subs                |
| PIX com `subaccountId`      | Cobrança/saque/reembolso na subconta |

[Consultar taxas](/api-reference/endpoint/subaccount/pricing) antes de `set-pricing` para ver `totalPercentFee` / `totalFixedFee` por operação.

## Limites e bloqueio

**Limites** (`set-limits`): valores em reais ou `null` para remover. Gasto validado por agregação de transações de débito `COMPLETED` vinculadas à subconta (fuso America/Sao\_Paulo).

**Bloqueio** (`lock`):

| `mode`          | Depósito PIX / add-balance | Saque PIX / remove-balance |
| --------------- | -------------------------- | -------------------------- |
| `full`          | Bloqueado                  | Bloqueado                  |
| `deposit_only`  | Bloqueado                  | Permitido                  |
| `withdraw_only` | Permitido                  | Bloqueado                  |

## MED e reembolso

* **MED:** quando o depósito PIX estava vinculado à subconta (`subaccountId` na cobrança), o bloqueio reduz o **disponível da subconta** e aumenta `lockedPadrao` — **não** usa `blockedAmount` da conta principal. MED em PIX da conta principal segue o fluxo normal na main. Veja também [Disputas MED](/api-reference/guides/pix#meds).
* **Reembolso PIX:** a taxa de saída segue o pricing da subconta; o débito reserva saldo na **subconta** (líquido retido + taxa). Informe `subaccountId` em `POST /refunds/create` quando o depósito pertence à subconta. Na conclusão do estorno, lucro de subconta creditado na main pode ser revertido.

  [Solicitar reembolso](/api-reference/endpoint/refunds/create)

## Taxas (PIX entrada e PIX saída)

Subcontas pagam: **taxa da conta principal + acréscimo configurado**.

| Operação                  | `operation` na API    |
| ------------------------- | --------------------- |
| PIX entrada (cobrança)    | `PIX_PADRAO_DEPOSIT`  |
| PIX saída (transferência) | `PIX_PADRAO_TRANSFER` |

* **API pública:** `POST /subaccount/set-pricing` define acréscimo por subconta. O valor soma à taxa da conta principal; na liquidação do PIX in, o acréscimo credita a conta principal (`SUBACCOUNT_PROFIT`).
* **Preview:** `GET /subaccount/pricing` com `id` ou `externalReference` retorna simulação antes de cobrar.

  [Definir taxas](/api-reference/endpoint/subaccount/set-pricing)

## Endpoints

<CardGroup cols={2}>
  <Card title="Criar" icon="plus" href="/api-reference/endpoint/subaccount/create">
    Nova subconta com `externalReference`.
  </Card>

  <Card title="Consultar" icon="magnifying-glass" href="/api-reference/endpoint/subaccount/get">
    Por `id` na URL.
  </Card>

  <Card title="Por referência" icon="hashtag" href="/api-reference/endpoint/subaccount/get-by-ref">
    `GET .../get-by-ref/{externalReference}`.
  </Card>

  <Card title="Listar" icon="list" href="/api-reference/endpoint/subaccount/list">
    Paginação e filtro `status`.
  </Card>

  <Card title="Saldo" icon="wallet" href="/api-reference/endpoint/subaccount/balance">
    Query `id` ou `externalReference`.
  </Card>

  <Card title="Adicionar saldo" icon="arrow-down" href="/api-reference/endpoint/subaccount/add-balance">
    Main → subconta.
  </Card>

  <Card title="Remover saldo" icon="arrow-up" href="/api-reference/endpoint/subaccount/remove-balance">
    Subconta → main.
  </Card>

  <Card title="Transferir entre subs" icon="right-left" href="/api-reference/endpoint/subaccount/transfer">
    `fromSubaccountId` → `toSubaccountId`.
  </Card>

  <Card title="Atualizar" icon="pen" href="/api-reference/endpoint/subaccount/update">
    Nome e status `ACTIVE` / `DISABLED`.
  </Card>

  <Card title="Excluir" icon="trash" href="/api-reference/endpoint/subaccount/delete">
    Saldo zerado no Padrão.
  </Card>

  <Card title="Bloquear" icon="lock" href="/api-reference/endpoint/subaccount/lock">
    `full`, `withdraw_only`, `deposit_only`.
  </Card>

  <Card title="Desbloquear" icon="lock-open" href="/api-reference/endpoint/subaccount/unlock">
    Volta ao modo normal.
  </Card>

  <Card title="Limites" icon="gauge" href="/api-reference/endpoint/subaccount/set-limits">
    Diário, mensal e por transação.
  </Card>

  <Card title="Taxas" icon="percent" href="/api-reference/endpoint/subaccount/set-pricing">
    Acréscimo PIX in/out.
  </Card>
</CardGroup>

<Note>
  Para excluir uma subconta, zere o saldo (`remove-balance` ou saques) e use `POST /subaccount/delete`. A resposta confirma com `{ "id": "..." }`. Subcontas com saldo retornam erro 400.
</Note>