Consultar no painel
Abra Integrações → Subcontas, ou Ver subcontas no menu da operação principal no topo da sidebar. A página mostra as subcontas criadas pela API, seus saldos disponíveis e as datas de criação, com paginação. Abra uma linha para ver os detalhes e copiar seu identificador. O card Saldo nesta página soma apenas as subcontas listadas; o saldo principal é apresentado separadamente. O painel continua na única operação principal: consultar uma subconta não muda o contexto de recebimentos ou saques da dashboard. A criação e as movimentações das subcontas continuam pela API.Criar
POST https://api.pagmaster.site/api/v1/subaccounts exige a permissão subaccounts. Gere uma key em Integrações → Keys com essa permissão e as permissões financeiras necessárias.
requestKey é um UUID: preserve a mesma referência para repetir uma criação sem duplicar a subconta, inclusive após renomeá-la. Usar a mesma referência para outro nome ou para uma subconta excluída retorna 400. Os valores acima são ilustrativos.
As rotas de gestão também aceitam /api/v1/public/subaccounts, para integrações que já usam a base pública.
Selecionar em qualquer rota financeira
Use a mesma API key e envie o ID retornado emX-Master-Subaccount:
Os caminhos financeiros continuam relativos a
https://api.pagmaster.site/api/v1/public. Não é preciso mudar o corpo das requisições.
O saldo cripto é separado de BRL. A resposta de uma subconta inclui cryptoBalanceUnits, cryptoReservedUnits, cryptoCurrency: "usdt" e cryptoUnitScale: 1000000. Uma subconta com saldo ou movimentação cripto pendente não pode ser excluída.
X-Master-Operation/operationId e X-Master-Subaccount) retornam 400. IDs de outra conta, excluídos ou referentes à principal no header de subconta retornam 404.
As permissões da key continuam obrigatórias: selecionar uma subconta não concede permissão para criar cobranças ou enviar dinheiro. A gestão de subcontas opera sobre a conta proprietária; o header não cria hierarquias de subcontas. Keys, perfil e endpoints de webhook permanecem compartilhados e são administrados pelo painel.
Saldo e segurança financeira
Recebimentos confirmados são registrados uma única vez no ledger da subconta correspondente. Cartão mantém sua retenção até a liberação. Reservas de saque bloqueiam apenas o saldo da origem, e uma subconta não pode utilizar valores da principal nem de outra subconta. O mínimo de saque continua sendo R$ 10,00, com a taxa da conta incluída no débito bruto. Taxas e bloqueios globais ou individuais são herdados da conta principal. Não existe parâmetro de criação para definir saldo ou contornar essas condições. Referências de pagamentorequestKey continuam únicas por conta proprietária: use UUIDs distintos entre cobranças diferentes, inclusive em subcontas diferentes.
Listar e consultar
GET /subaccounts?page=1&pageSize=25 exige read. Retorna { subaccounts, total, page, pageSize }. pageSize aceita 1–100, e page aceita 1–10000. GET /subaccounts/{id} retorna uma subconta da mesma conta com seu saldo disponível em centavos.
Renomear e excluir
PATCH /subaccounts/{id} recebe { "name": "Novo nome" } e exige subaccounts. O ID e o histórico permanecem os mesmos.
DELETE /subaccounts/{id}, com Content-Type: application/json e corpo {}, exige subaccounts. Só permite excluir quando o saldo estiver zerado, conciliado, sem reservas e sem pagamentos ou saques em andamento. Recebimentos no cartão ainda retidos também impedem a exclusão. A resposta é { "ok": true }.
O registro é arquivado, preservando pagamentos e lançamentos para auditoria. Uma subconta arquivada não pode receber novas movimentações. A principal não pode ser excluída nem selecionada como subconta. Repetir a exclusão sem enviar o header da subconta já arquivada é idempotente.
Eventos e migração
Os webhooks da conta recebem os eventos de suas subcontas.data.subaccountId identifica a subconta; é null para movimentações da principal. operationId permanece como identificador do contexto financeiro para compatibilidade. A assinatura e a política de tentativas permanecem as mesmas.
O antigo sistema de múltiplas operações foi encerrado: /operations, /operations/{id} e suas variantes públicas não estão mais disponíveis. As operações secundárias existentes são convertidas em subcontas, preservando IDs, nomes, saldos e histórico. A principal atual é mantida. Chaves antigas com operations continuam autorizadas a gerenciar subcontas por compatibilidade; para novas chaves, selecione subaccounts.