Subcontas White-Label (BaaS)

A API de Subcontas White-Label transforma sua conta Dotfy em uma plataforma de pagamentos própria (modelo Banking-as-a-Service): você (o master) cria e opera subcontas de terceiros — seus clientes/parceiros — totalmente sob a sua marca, usando apenas a sua API key.

Pré-requisitos

As rotas /api/subaccounts/* só existem para contas habilitadas. Sem isso elas respondem 404 (são invisíveis — não vazam sequer a existência da feature). É necessário:

a flag whiteLabelEnabled ativa na sua conta (liberada pelo time Dotfy);

a API key com os escopos subaccounts:read e/ou subaccounts:write.

Todas as chamadas são autenticadas pela sua API key do master: Authorization: Bearer {{api_key}}.

Modelo headless

A subconta é headless: não tem login, painel, nem endpoints de webhook próprios. Quem opera é sempre o master, via /api/subaccounts/{id}/.... Por isso todos os eventos da subconta (KYC, chave PIX e cobranças) são entregues nos endpoints de webhook do master — basta inscrever seu endpoint nos eventos EVENT:SUBACCOUNT_* e EVENT:CHARGE_*.

Fluxo típico

Criar a subconta — POST {{base_url}}/api/subaccounts (escopo subaccounts:write).

Enviar KYC — POST {{base_url}}/api/subaccounts/{{subaccount_id}}/kyc com os documentos do responsável/empresa.

Aprovação — o time Dotfy revisa e decide; você recebe EVENT:SUBACCOUNT_KYC_APPROVED ou EVENT:SUBACCOUNT_KYC_REJECTED no endpoint do master.

Cadastrar chave PIX — POST {{base_url}}/api/subaccounts/{{subaccount_id}}/pix-keys; após a revisão chega EVENT:SUBACCOUNT_PIX_KEY_APPROVED ou ..._REJECTED. A chave precisa pertencer ao mesmo titular da subconta (senão PIX_KEY_OWNERSHIP_MISMATCH).

Operar — emitir cobranças (/charges), consultar saldo e extrato, solicitar saques e configurar taxas, todos sob /api/subaccounts/{{subaccount_id}}/....

Convenções

Unidades monetárias: no envio (POST) os valores vão em reais (ex.: value: 29.90); nas respostas e webhooks os valores vêm em centavos (ex.: amount: 2990).

Sigilo da comissão: a sua comissão como master nunca aparece para a subconta. No saldo, extrato e cobranças da subconta existe apenas a taxa de gateway cheia (gatewayFee). A decomposição da sua comissão fica exclusivamente no extrato do próprio master, fora deste escopo.

Subcontas White-Label (BaaS)