Guides/Payment flows

Empresas filhas e subaccounts

Create empresas filhas pela API e mover balance entre a conta principal e cada subaccount.

Uma subconta representa uma empresa filha vinculada à sua empresa principal na KyvoPay. Ela pode ser criada e gerenciada pela API usando a mesma X-API-Key da empresa principal.

Fluxo recomendado

  1. Crie a empresa filha

    Use POST /v1/subaccounts com nome e CPF/CNPJ. A empresa principal é identificada automaticamente pela chave de API.

  2. Guarde o ID da subconta

    A resposta retorna id. Use esse valor como subaccount_id nas operações de saldo.

  3. Mova saldo quando precisar

    Use POST /v1/transfers com direction: "to_subaccount" para enviar saldo para a empresa filha ou direction: "from_subaccount" para trazer saldo de volta.

Criar uma empresa filha

curl -X POST https://integrate.api.kyvopay.com.br/v1/subaccounts \
  -H "X-API-Key: ky_XXXXX-XXXXX-XXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Filial Centro",
    "document": "12345678909",
    "external_reference": "filial-centro"
  }'

Enviar saldo para a empresa filha

curl -X POST https://integrate.api.kyvopay.com.br/v1/transfers \
  -H "X-API-Key: ky_XXXXX-XXXXX-XXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "subaccount_id": "01HZ8K3M5N",
    "direction": "to_subaccount",
    "amount_centavos": 10000,
    "idempotency_key": "repasse-filial-001"
  }'
Criar empresa filha

Veja todos os campos aceitos no cadastro.

Transferir saldo

Mova saldo entre a empresa principal e a subconta.

Need help? Contact support
© 2026 KyvoPay