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

# Subcontas & Gestão White-label

> Crie e gerencie subcontas isoladas, saldos dedicados, precificação personalizada (spread markup), travas operacionais e transferências internas.

O sistema de **Subcontas da KavroPay** foi projetado no padrão das maiores fintechs globais (como GoatPay e Stripe Connect), permitindo que plataformas, franquias, ERPs, SaaS e marketplaces criem **carteiras digitais segregadas** para seus parceiros, lojistas ou filiais.

Cada subconta possui seu próprio saldo isolado, regras de precificação customizadas com margem de lucro (markup spread) para a conta Master, controle de limites e livro-razão contábil (*double-entry ledger*).

```mermaid theme={null}
flowchart TD
    M[Conta Master] -->|Add Balance / Remove Balance| S1[Subconta 1 - Loja Centro]
    M -->|Add Balance / Remove Balance| S2[Subconta 2 - Loja Sul]
    S1 <-->|Transferência Direta| S2
    
    C[Cliente Final Paga PIX R$ 100,00] --> G(KavroPay Gateway)
    G -->|Taxa KavroPay Base: R$ 1,49| K[KavroPay]
    G -->|Spread de Lucro Master: R$ 2,00| M
    G -->|Saldo Líquido: R$ 96,51| S1
```

***

## Compatibilidade Dual de Rotas

Para máxima facilidade de migração e suporte a clientes legados (incluindo clientes do ecossistema GoatPay), a API KavroPay disponibiliza rotas duplas:

* **Padrão RESTful (Recomendado):** `/v1/subaccounts/*`
* **Padrão GoatPay (Legado):** `/v1/subaccount/*`

Ambos os padrões são intercambiáveis e acessam a mesma infraestrutura contábil de alta performance.

***

## 1. Criar uma Nova Subconta

<api-endpoint method="POST" path="/v1/subaccounts" />

Cria uma carteira digital independente vinculada à sua conta Master.

### Parâmetros do Payload

| Campo | Tipo | Obrigatório | Descrição |
| :- | :- | :- | :- |
| `name` | string | **Sim** | Razão social ou nome de fantasia da subconta (mínimo 2 caracteres). |
| `document` | string | Opcional | CPF ou CNPJ do titular da subconta (com ou sem pontuação). |
| `email` | string | Opcional | E-mail para contato e identificação da subconta. |
| `phone` | string | Opcional | Telefone / WhatsApp com DDD. |
| `externalReference` | string | Opcional | Seu ID interno único para a subconta (ex: `"LOJA_01"`). |
| `markupFixed` | string \| number | Opcional | Spread fixo adicional da Master em Reais (ex: `"0.50"` para R\$ 0,50). |
| `markupFixedCents` | integer | Opcional | Spread fixo adicional em centavos (ex: `50`). |
| `markupPercent` | number | Opcional | Spread percentual adicional da Master (ex: `1.0` para 1,00%). |
| `withdrawalFee` | string \| number | Opcional | Taxa cobrada da subconta em cada saque PIX em Reais (ex: `"1.50"`). |
| `dailyLimit` | string \| number | Opcional | Limite financeiro diário de cobrança/saque da subconta (ex: `"10000.00"`). |
| `maxTransaction` | string \| number | Opcional | Valor máximo permitido por cobrança/saque (ex: `"2000.00"`). |
| `webhookUrl` | string | Opcional | URL para envio de webhooks exclusivos desta subconta. |
| `metadata` | object | Opcional | Chave-valor com metadados livres adicionais. |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.kavropay.online/v1/subaccounts \
    -H "Authorization: Bearer sk_live_sua_chave_aqui" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Filial Loja Centro",
      "document": "12345678000199",
      "email": "filial.centro@empresa.com",
      "phone": "11988887777",
      "externalReference": "FILIAL-CENTRO-01",
      "markupFixed": "0.50",
      "markupPercent": 1.0,
      "withdrawalFee": "2.00",
      "maxTransaction": "5000.00"
    }'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  async function createSubaccount() {
    const response = await axios.post('https://api.kavropay.online/v1/subaccounts', {
      name: 'Filial Loja Centro',
      document: '12345678000199',
      email: 'filial.centro@empresa.com',
      phone: '11988887777',
      externalReference: 'FILIAL-CENTRO-01',
      markupFixed: '0.50',
      markupPercent: 1.0,
      withdrawalFee: '2.00',
      maxTransaction: '5000.00'
    }, {
      headers: {
        'Authorization': 'Bearer sk_live_sua_chave_aqui',
        'Content-Type': 'application/json'
      }
    });

    console.log('Subconta criada:', response.data);
  }

  createSubaccount();
  ```

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

  url = "https://api.kavropay.online/v1/subaccounts"
  headers = {
      "Authorization": "Bearer sk_live_sua_chave_aqui",
      "Content-Type": "application/json"
  }

  payload = {
      "name": "Filial Loja Centro",
      "document": "12345678000199",
      "email": "filial.centro@empresa.com",
      "phone": "11988887777",
      "externalReference": "FILIAL-CENTRO-01",
      "markupFixed": "0.50",
      "markupPercent": 1.0,
      "withdrawalFee": "2.00",
      "maxTransaction": "5000.00"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```php PHP theme={null}
  <?php
  $payload = [
    "name" => "Filial Loja Centro",
    "document" => "12345678000199",
    "email" => "filial.centro@empresa.com",
    "phone" => "11988887777",
    "externalReference" => "FILIAL-CENTRO-01",
    "markupFixed" => "0.50",
    "markupPercent" => 1.0,
    "withdrawalFee" => "2.00",
    "maxTransaction" => "5000.00"
  ];

  $ch = curl_init("https://api.kavropay.online/v1/subaccounts");
  curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer sk_live_sua_chave_aqui",
      "Content-Type: application/json"
    ]
  ]);

  $result = curl_exec($ch);
  curl_close($ch);
  echo $result;
  ```
</CodeGroup>

### Resposta de Sucesso (HTTP 201 Created)

```json theme={null}
{
  "id": "e4a1b2c3-9876-4321-abcd-ef0123456789",
  "name": "Filial Loja Centro",
  "document": "12345678000199",
  "email": "filial.centro@empresa.com",
  "phone": "11988887777",
  "externalReference": "FILIAL-CENTRO-01",
  "status": "active",
  "balance": {
    "available": 0.00,
    "availableCents": 0,
    "locked": 0.00,
    "lockedCents": 0,
    "currency": "BRL"
  },
  "pricing": {
    "markupFixed": 0.50,
    "markupFixedCents": 50,
    "markupPercent": 1.00,
    "markupPercentBps": 100,
    "withdrawalFee": 2.00,
    "withdrawalFeeCents": 200
  },
  "limits": {
    "dailyLimit": null,
    "monthlyLimit": null,
    "maxTransaction": 5000.00
  },
  "createdAt": "2026-09-28T20:00:00.000Z",
  "updatedAt": "2026-09-28T20:00:00.000Z"
}
```

***

## 2. Listar e Consultar Subcontas

<api-endpoint method="GET" path="/v1/subaccounts" />

Lista todas as subcontas cadastradas sob a conta Master com suporte a filtros e paginação.

### Parâmetros de Query String

* `page`: Número da página (padrão: `1`).
* `limit`: Quantidade de itens por página (máx: `100`, padrão: `20`).
* `search`: Busca textual por nome, documento, e-mail ou `externalReference`.
* `status`: Filtrar por `'active'`, `'locked'` ou `'disabled'`.

```bash cURL theme={null}
curl -X GET "https://api.kavropay.online/v1/subaccounts?status=active&page=1&limit=20" \
  -H "Authorization: Bearer sk_live_sua_chave_aqui"
```

<api-endpoint method="GET" path="/v1/subaccounts/{id}" />

Obtém o detalhamento completo de uma subconta. Você pode informar o **UUID da subconta** ou o seu **`externalReference`**.

```bash cURL theme={null}
curl -X GET "https://api.kavropay.online/v1/subaccounts/FILIAL-CENTRO-01" \
  -H "Authorization: Bearer sk_live_sua_chave_aqui"
```

***

## 3. Gestão de Saldo e Transferências Internas

O motor de subcontas da KavroPay inclui suporte nativo a liquidação e movimentação interna entre carteiras com atualização atômica e conciliação em partida dobrada.

### Aporte de Saldo (Master ➔ Subconta)

<api-endpoint method="POST" path="/v1/subaccounts/{id}/add-balance" />

Transfere saldo disponível da conta Master para uma subconta específica.

```json Payload theme={null}
{
  "amount": "150.00",
  "description": "Adiantamento para capital de giro filial"
}
```

### Resgate de Saldo (Subconta ➔ Master)

<api-endpoint method="POST" path="/v1/subaccounts/{id}/remove-balance" />

Resgata saldo da subconta de volta para a carteira da conta Master.

```json Payload theme={null}
{
  "amount": "50.00",
  "description": "Recolhimento semanal de royalties"
}
```

### Transferência Direta entre Subcontas (Subconta A ➔ Subconta B)

<api-endpoint method="POST" path="/v1/subaccounts/transfer" />

Transfere saldo diretamente de uma subconta de origem para uma subconta de destino sem passar pela conta Master.

```json Payload theme={null}
{
  "sourceSubaccountId": "FILIAL-CENTRO-01",
  "targetSubaccountId": "FILIAL-SUL-02",
  "amount": "100.00",
  "description": "Transferência de estoque entre filiais"
}
```

***

## 4. Monetização & Markup Spread da Master

Como proprietário da conta Master, você pode configurar uma margem de lucro sobre todas as transações realizadas pelas suas subcontas.

<api-endpoint method="PUT" path="/v1/subaccounts/{id}/pricing" />

```json Payload theme={null}
{
  "markupFixed": "0.50",
  "markupPercent": 1.50,
  "withdrawalFee": "2.50"
}
```

### Como o Spread é Calculado e Liquidado:

1. **Cobrança Base:** A KavroPay cobra da Master a taxa contratual (ex: 2,99% + R\$ 0,50).
2. **Markup da Master:** A Master cobra da subconta um acréscimo (ex: +1,50% + R\$ 0,50).
3. **Taxa Efetiva da Subconta:** A subconta paga 4,49% + R\$ 1,00.
4. **Liquidação Automática:** No momento em que o PIX é pago:
   * A **Subconta** recebe o valor líquido (R$ 100,00 - R$ 4,49 = R\$ 95,51).
   * A **Conta Master** recebe imediatamente o lucro de spread (+R\$ 2,00) em seu saldo disponível.
   * A **KavroPay** retém a taxa de processamento base.

<api-endpoint method="GET" path="/v1/subaccounts/{id}/pricing" />

Exibe a tabela comparativa entre as taxas base da KavroPay, o spread de lucro configurado e a taxa final paga pela subconta.

***

## 5. Travas Operacionais & Limites de Risco

### Bloqueio e Desbloqueio Temporário

<api-endpoint method="POST" path="/v1/subaccounts/{id}/lock" />

<api-endpoint method="POST" path="/v1/subaccounts/{id}/unlock" />

Permite pausar instantaneamente operações de cobrança e saque de uma subconta em caso de suspeita de fraude ou inadimplência.

### Configurar Limites

<api-endpoint method="PUT" path="/v1/subaccounts/{id}/limits" />

```json Payload theme={null}
{
  "dailyLimit": "50000.00",
  "maxTransaction": "5000.00"
}
```

***

## 6. Cobranças e Saques Vinculados a Subcontas

Para emitir cobranças ou saques em nome de uma subconta, basta informar o campo `subaccountId` (ou `subaccount_id`) na chamada padrão da API:

### Criar Cobrança PIX para Subconta

```bash cURL theme={null}
curl -X POST https://api.kavropay.online/v1/charges \
  -H "Authorization: Bearer sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "description": "Venda Loja Centro #8192",
    "subaccountId": "FILIAL-CENTRO-01",
    "customer": {
      "name": "Carlos Eduardo",
      "document": "12345678909"
    }
  }'
```

### Criar Saque PIX para Subconta

```bash cURL theme={null}
curl -X POST https://api.kavropay.online/v1/withdrawals \
  -H "Authorization: Bearer sk_live_sua_chave_aqui" \
  -H "Idempotency-Key: e9a1c2d3-1111-2222-3333-444455556666" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "80.00",
    "subaccountId": "FILIAL-CENTRO-01",
    "pix_key": "12345678000199",
    "pix_key_type": "CNPJ",
    "description": "Saque de faturamento semanal"
  }'
```

***

## 7. Extrato Contábil da Subconta (Statement)

<api-endpoint method="GET" path="/v1/subaccounts/{id}/statement" />

Retorna o histórico contábil de movimentações da subconta com conciliação auditada e saldo resultante após cada operação.

```json Resposta theme={null}
{
  "subaccountId": "e4a1b2c3-9876-4321-abcd-ef0123456789",
  "name": "Filial Loja Centro",
  "data": [
    {
      "id": "7f8a9b0c-1234-5678-90ab-cdef12345678",
      "direction": "credit",
      "refType": "payment",
      "refId": "PAY982A1B2C3D4E5F6",
      "amount": 96.51,
      "balanceAfter": 246.51,
      "description": "Pagamento recebido PAY982A1B2C3D4E5F6 (Líquido)",
      "createdAt": "2026-09-28T20:15:00.000Z"
    },
    {
      "id": "1a2b3c4d-5678-90ab-cdef-1234567890ab",
      "direction": "debit",
      "refType": "withdrawal",
      "refId": "WIT819A2B3C4D5E6F7",
      "amount": 82.00,
      "balanceAfter": 150.00,
      "description": "Saque PIX de R$ 80,00 (Taxa de saque: R$ 2,00)",
      "createdAt": "2026-09-28T19:30:00.000Z"
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 20
}
```

<CardGroup cols={2}>
  <Card title="Split de Pagamentos" icon="arrows-split-up-and-left" horizontal href="/split-de-pagamentos">
    Dividir valores entre parceiros no pagamento
  </Card>

  <Card title="Cobranças PIX" icon="qrcode" horizontal href="/cobrancas-pix">
    Criar cobranças e links de checkout
  </Card>
</CardGroup>