Subcontas & Gestão White-label

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

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

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.

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"
  }'

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();

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
$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;

Resposta de Sucesso (HTTP 201 Created)

{
  "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

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

cURL

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

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

cURL

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)

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

Payload

{
  "amount": "150.00",
  "description": "Adiantamento para capital de giro filial"
}

Resgate de Saldo (Subconta ➔ Master)

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

Payload

{
  "amount": "50.00",
  "description": "Recolhimento semanal de royalties"
}

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

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

Payload

{
  "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.

Payload

{
  "markupFixed": "0.50",
  "markupPercent": 1.50,
  "withdrawalFee": "2.50"
}

Como o Spread é Calculado e Liquidado:

Cobrança Base: A KavroPay cobra da Master a taxa contratual (ex: 2,99% + R$ 0,50).
Markup da Master: A Master cobra da subconta um acréscimo (ex: +1,50% + R$ 0,50).
Taxa Efetiva da Subconta: A subconta paga 4,49% + R$ 1,00.
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.

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

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

Configurar Limites

Payload

{
  "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

cURL

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

cURL

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)

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

Resposta

{
  "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
}

Split de Pagamentos

Dividir valores entre parceiros no pagamento

Cobranças PIX

Criar cobranças e links de checkout

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Subcontas & Gestão White-label

Compatibilidade Dual de Rotas

1. Criar uma Nova Subconta

Parâmetros do Payload

Resposta de Sucesso (HTTP 201 Created)

2. Listar e Consultar Subcontas

Parâmetros de Query String

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

Aporte de Saldo (Master ➔ Subconta)

Resgate de Saldo (Subconta ➔ Master)

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

4. Monetização & Markup Spread da Master

Como o Spread é Calculado e Liquidado:

5. Travas Operacionais & Limites de Risco

Bloqueio e Desbloqueio Temporário

Configurar Limites

6. Cobranças e Saques Vinculados a Subcontas

Criar Cobrança PIX para Subconta

Criar Saque PIX para Subconta

7. Extrato Contábil da Subconta (Statement)

Split de Pagamentos

Cobranças PIX

​Compatibilidade Dual de Rotas

​1. Criar uma Nova Subconta

​Parâmetros do Payload

​Resposta de Sucesso (HTTP 201 Created)

​2. Listar e Consultar Subcontas

​Parâmetros de Query String

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

​Aporte de Saldo (Master ➔ Subconta)

​Resgate de Saldo (Subconta ➔ Master)

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

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

​Como o Spread é Calculado e Liquidado:

​5. Travas Operacionais & Limites de Risco

​Bloqueio e Desbloqueio Temporário

​Configurar Limites

​6. Cobranças e Saques Vinculados a Subcontas

​Criar Cobrança PIX para Subconta

​Criar Saque PIX para Subconta

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

Split de Pagamentos

Cobranças PIX

Compatibilidade Dual de Rotas

1. Criar uma Nova Subconta

Parâmetros do Payload

Resposta de Sucesso (HTTP 201 Created)

2. Listar e Consultar Subcontas

Parâmetros de Query String

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

Aporte de Saldo (Master ➔ Subconta)

Resgate de Saldo (Subconta ➔ Master)

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

4. Monetização & Markup Spread da Master

Como o Spread é Calculado e Liquidado:

5. Travas Operacionais & Limites de Risco

Bloqueio e Desbloqueio Temporário

Configurar Limites

6. Cobranças e Saques Vinculados a Subcontas

Criar Cobrança PIX para Subconta

Criar Saque PIX para Subconta

7. Extrato Contábil da Subconta (Statement)