O que uma subconta é (e o que não é)
É
Um ledger com saldo próprio dentro da sua conta.Criada por API, na hora, sem documento nem aprovação.Extrato permanente de tudo que entrou e saiu.
Não é
Uma conta PurinCash: não tem login, painel nem chave de API própria.Um destino de dinheiro real: o valor continua na carteira da sua conta.Um cadastro com KYC: a relação com o cliente final é sua.
O dinheiro real fica sempre na sua carteira, e o saldo da subconta diz que fatia dele
pertence a cada cliente. É por isso que criar subconta é instantâneo — e é por isso que
um bug seu de atribuição nunca move dinheiro de verdade: a camada é contábil.
Criando uma subconta
Resposta 201
string
required
Nome do cliente. Até 100 caracteres.
string
O ID do cliente no seu sistema. Vale usar sempre: ele é único por ambiente, e criar
de novo com o mesmo
externalId devolve 409 com o subaccountId da existente — ou
seja, a criação vira idempotente e o retry do seu código nunca duplica cliente.string
Contato do cliente. Informativo, não autentica nada.
string
String JSON de até 2 KB, devolvida sem alteração.
sacc_... junto do cadastro
do seu cliente: é ele que você vai usar em todas as outras chamadas.
Cobrando para uma subconta
AdicionesubaccountId na criação da cobrança. Funciona em POST /v1/charges e em
POST /v1/payments, com PIX:
charge.paid / payment.paid vem com o campo subaccountId quando a
cobrança tem subconta, então o seu handler sabe de quem é a venda sem consultar nada:
O valor creditado no ledger é o líquido — o mesmo que entrou na sua carteira, já
sem a taxa do gateway. Assim a soma dos saldos das subcontas nunca promete mais
dinheiro do que existe.
Onde subaccountId não entra
Consultando saldo e extrato
amountCents vêm com sinal — crédito positivo, débito negativo — então somar a
coluna reproduz o saldo. O refId amarra cada lançamento à origem: psc_/psa_ é uma
venda (dá pra consultar a cobrança), tr_ é uma transferência.
GET /v1/subaccounts lista todas com saldo, e aceita ?externalId= pra achar um
cliente pelo seu ID sem guardar o sacc_ do lado de lá.
Transferindo saldo
POST /v1/subaccounts/{id}/transfer move valor entre a subconta e a sua conta, nos
dois sentidos. É uma operação contábil — nenhum PIX é disparado:
to_master exige saldo suficiente na subconta, e a checagem é atômica: duas
transferências concorrentes nunca deixam o saldo negativo. A description aparece no
extrato — capriche nela, é o que o seu financeiro vai ler depois.
Pagando o cliente de verdade
Quando chega a hora de repassar o saldo pro seu cliente, são dois passos, e o segundo você já conhece:1
Traga o saldo pra conta principal
POST /v1/subaccounts/{id}/transfer com direction: "to_master" e o valor do
repasse. Isso debita o ledger do cliente e documenta o repasse no extrato dele.2
Saque com a chave PIX do cliente
POST /v1/payouts com method: "pix" e o walletAddress sendo a
chave PIX do cliente. O dinheiro real sai da sua carteira — que é onde ele sempre
esteve.Desativando
PUT /v1/subaccounts/{id} com active: false. A subconta some das novas cobranças e
não aceita mais entradas, mas o saldo continua consultável e o to_master continua
funcionando — desativar não prende dinheiro. Excluir não existe: o extrato é histórico
financeiro e histórico financeiro não se apaga.
Em sandbox
Tudo funciona com chaveps_test_, com o mesmo isolamento do resto da API: subcontas
de teste são separadas das reais. No simulate-paid o ledger é creditado com o valor
cheio (sandbox não tem taxa), então dá pra testar o ciclo inteiro — criar subconta,
cobrar, simular pagamento, ver o saldo mudar, transferir — sem mover um centavo.
Referência completa
Os 6 endpoints de subcontas com playground, na seção Subcontas da Referência.