Subcontas

Atribua vendas a cada cliente seu, envie, transfira, divida a venda e saque para a chave Pix dele.

Uma subconta representa um cliente seu (um vendedor do seu marketplace, um franqueado, um parceiro). O dinheiro continua no seu saldo; a subconta guarda quanto dele é atribuído a esse cliente, e essa parte não sai nos seus saques, Pix e transferências (só no saque da própria subconta). Uma cobrança criada com subaccountId (ou dividida entre subcontas com split), quando paga, credita a cada subconta a parte dela − tarifa da WyzeCash na mesma proporção − sua comissão. Estorno ou devolução (MED) de uma venda saem de cada subconta na mesma proporção.

Em toda rota /v1/subaccounts/{id} (e no subaccountId da cobrança e do link), {id} aceita o sacc_... ou o seu externalId.

Entra na subconta	Sai da subconta
venda de uma cobrança ou link ligado a ela (sale)	saque para o cliente (withdraw)
envio da sua conta principal (fund)	devolução à conta principal (return)
transferência de outra subconta (transfer)	transferência para outra subconta (transfer)
saque que não saiu, de volta (withdraw)	estorno ou MED de uma venda (refund, med)

​

Criar uma subconta

POST /v1/subaccounts · escopo subaccounts:write

name · string · required

2 a 80 caracteres. Vai mudar: o nome vai seguir o titular (nome completo para CPF, razão social para CNPJ), sem CPF/CNPJ nem id no nome; veja a regra do nome.

email · string | null

E-mail do cliente (guardado criptografado). A lista devolve só hasEmail; criar, consultar e editar devolvem o e-mail.

externalId · string | null

O identificador do cliente no seu sistema (letras, números, ponto, hífen e sublinhado; até 64). Único por conta: 409 EXTERNAL_ID_IN_USE.

saleFeeBps · integer

Sua comissão por venda em pontos-base (100 = 1%; 0 a 10000).

saleFeeFixed · integer

Parte fixa da comissão por venda, em centavos.

withdrawFeeBps · integer

Sua taxa por saque da subconta, em pontos-base.

withdrawFeeFixed · integer

Parte fixa da taxa por saque, em centavos. Ela paga a tarifa do saque da WyzeCash; o que sobra fica com você.

feeMode · "global" | "custom"

global segue a taxa global da Configuração das subcontas; custom usa as taxas acima. Sem feeMode e sem nenhuma taxa no pedido, a subconta nasce na global; com alguma taxa, fica com a própria.

pixKey · object | null

{ "keyType": "cpf" | "cnpj" | "email" | "phone" | "random", "key": "..." }: a chave Pix do cliente, conferida no banco e guardada criptografada. Vira o destino padrão do saque da subconta (não precisa mandar a chave em cada saque). Volta com o titular e o banco: inteira ao criar, consultar e editar, mascarada na lista.

metadata · object | null

Dados livres do seu sistema (objeto JSON, até 2 KB). Volta na consulta da subconta.

curl -X POST https://bukio-backend-production.up.railway.app/v1/subaccounts \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ateliê da Ana", "externalId": "vendedor-42", "saleFeeBps": 500, "withdrawFeeFixed": 200, "pixKey": { "keyType": "email", "key": "[e-mail]" }, "metadata": { "plano": "pro" } }'

{
  "id": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f",
  "name": "Ateliê da Ana",
  "externalId": "vendedor-42",
  "hasEmail": false,
  "saleFee": { "percentBps": 500, "fixed": 0 },
  "withdrawFee": { "percentBps": 0, "fixed": 200 },
  "balance": 0,
  "active": true,
  "pixKey": { "keyType": "email", "key": "[e-mail]", "holderName": "Ana S.", "institution": "Banco Exemplo" },
  "createdAt": "2026-10-08T15:00:00.000Z",
  "email": null,
  "metadata": { "plano": "pro" }
}

balance é o saldo atribuído à subconta (centavos), nunca negativo. saleFee e withdrawFee são as taxas que valem (na global, as da Configuração) e feeMode diz de onde vêm.

​

Bloqueios

Uma subconta pode estar bloqueada de dois jeitos, e os dois aparecem no detalhe e na lista:

Campo	Quem muda	Valores
lockMode	você, no painel ou em Editar subconta	none, receive (não recebe cobrança nova, envio da principal nem transferência), withdraw (não saca nem transfere para outra subconta, mas devolve à principal) ou full (os dois)
platformLock	só a WyzeCash	none, receive (entrada bloqueada), withdraw (saída bloqueada: não saca, não transfere, não devolve à principal e não pode ser excluída) ou full (entrada e saída)

O platformLock vale junto com o lockMode e só a WyzeCash tira: fale com o suporte em Ajuda, no painel. O que estiver bloqueado responde 422 SUBACCOUNT_LOCKED, com a mensagem dizendo qual bloqueio (ex.: “A WyzeCash bloqueou a saída de dinheiro desta subconta. Fale com o suporte em Ajuda.”). A venda já criada e paga depois de um bloqueio de entrada fica com você, na conta principal.

​

Configuração das subcontas

Uma configuração por conta, que vale para todas as subcontas sem configuração própria. Só o dono da conta muda.

Método	Rota	Escopo	O que faz
GET	/v1/subaccounts/settings	subaccounts:get	a taxa global, os limites padrão e o bloqueio automático por MED
PUT	/v1/subaccounts/settings	subaccounts:update	muda o que vier no pedido
GET	/v1/subaccounts/settings/preview	subaccounts:get	quanto fica com você, com a subconta e com a WyzeCash numa venda e num saque, com a taxa informada

• Taxa global: a sua comissão por venda e taxa por saque das subcontas com feeMode: "global". Começa zerada. Mudar a global muda todas as que seguem a global.
• Limites padrão: copiados para cada subconta criada depois (o que o pedido manda vale por cima).
• Bloqueio automático por MED (medAutoLock, desligado de início): um MED numa venda da subconta sem saldo livre para reservar a parte dela tranca o saque dela (medLocked: true) e o que falta fica pendente (medPending). As próximas entradas dela (venda, envio, transferência) cobrem a pendência, nunca o seu saldo; sem pendência, ela destrava sozinha. Veja Mudar a configuração.

​

Listar, ver e alterar

Método	Rota	Escopo	O que faz
GET	/v1/subaccounts?limit=&cursor=	transactions:read	subcontas com saldo atribuído e o total atribuído
GET	/v1/subaccounts/{id}	transactions:read	uma subconta
PATCH	/v1/subaccounts/{id}	subaccounts:write	mesmos campos (todos opcionais; null apaga pixKey e metadata) e active para ativar ou desativar
DELETE	/v1/subaccounts/{id}	subaccounts:write	exclui: o saldo volta à conta principal e o externalId fica livre

Desativada (active: false): não recebe venda, envio nem transferência e não saca (SUBACCOUNT_INACTIVE); a venda paga depois fica com você. Devolver à principal continua valendo.

​

Movimentos da subconta

GET /v1/subaccounts/{id}/entries?limit=&cursor=&from=&to=&kind= · escopo transactions:read

Filtros opcionais: from e to (AAAA-MM-DD vale o dia inteiro em Brasília; com data e hora ISO, to é exclusivo) e kind (um ou mais tipos separados por vírgula).

{
  "items": [
    { "id": "SUB-2W8M4Z3F7K9Q", "kind": "sale", "kindTitle": "Venda creditada", "direction": "credit", "amount": 14200, "gross": 15000, "fee": 800, "description": "Cobrança BKY-7KQ2M9XP4RZT", "createdAt": "2026-10-08T15:04:11.000Z" }
  ],
  "nextCursor": null
}

kind	O que é
sale	venda creditada (gross = valor da cobrança, fee = tarifa + sua comissão, amount = o que ficou para a subconta)
fund	enviado da sua conta principal
transfer	transferência entre subcontas (direction diz se entrou ou saiu)
withdraw	saque para o cliente (fee = o que não foi para o cliente: sua taxa ou a tarifa)
return	devolvido à sua conta principal
refund	estorno de uma venda
med	devolução por MED de uma venda
adjust	ajuste

​

Enviar, transferir e devolver

Sem tarifa e sem dinheiro saindo da WyzeCash: só muda de quem é cada parte do seu saldo. As três pedem Idempotency-Key (repetir com os mesmos dados devolve o mesmo movimento; com outros dados, IDEMPOTENCY_KEY_REUSED).

Método	Rota	Corpo	O que faz
POST	/v1/subaccounts/{id}/fund	{ amount, description? }	envia do seu saldo livre para a subconta (o que já é das subcontas não conta: SUBACCOUNT_FUNDS)
POST	/v1/subaccounts/{id}/transfer	{ to, amount, description? }	passa saldo para outra subconta sua (to: sacc_... ou externalId); as duas ativas e diferentes
POST	/v1/subaccounts/{id}/return	{ amount, description? }	devolve à sua conta principal (vale com a subconta desativada)

{
  "id": "SUB-4Z3F7K9Q2W8M",
  "kind": "transfer",
  "kindTitle": "Transferência entre subcontas",
  "direction": "debit",
  "amount": 2000,
  "gross": null,
  "fee": 0,
  "description": "Repasse de setembro",
  "createdAt": "2026-10-08T15:20:00.000Z",
  "subaccount": { "id": "sacc_9f1c...", "externalId": "vendedor-42", "balance": 3000 },
  "to": { "id": "sacc_1b2c...", "externalId": "vendedor-77", "balance": 2000 }
}

​

Excluir

DELETE /v1/subaccounts/{id} · escopo subaccounts:write

O saldo volta à sua conta principal (um movimento return), a subconta some das listas e da API e o externalId fica livre para outra. O extrato dela fica guardado. Com saque dela em andamento: 409 SUBACCOUNT_BUSY, espere concluir.

{ "deleted": true, "id": "sacc_9f1c...", "externalId": "vendedor-42", "name": "Ateliê da Ana", "returned": 3000 }

​

Dividir uma venda entre subcontas

Na criação da cobrança, split (no lugar de subaccountId) divide a venda entre até 10 subcontas, cada uma com um valor em centavos; a soma vai até o valor da cobrança e o resto fica com você.

{ "amount": 10000, "split": [{ "subaccountId": "vendedor-42", "amount": 6000 }, { "subaccountId": "vendedor-77", "amount": 3000 }] }

Paga, cada subconta recebe a parte dela menos a tarifa da WyzeCash na mesma proporção e a sua comissão. A cobrança volta com split (subconta, nome e valor). Um link de pagamento também pode creditar numa subconta (subaccountId); se ela estiver desativada, quem paga não é barrado e a venda fica com você.

​

O saldo dos clientes é protegido

GET /v1/balance traz subaccounts (a soma do que é das subcontas) e free (o que é seu). Seus saques, Pix enviados e transferências só usam o free (SUBACCOUNT_FUNDS); o dinheiro das subcontas só sai no saque delas.

​

Avisos

Cada movimento manda o webhook subaccount.credited (entrou) ou subaccount.debited (saiu), com o saldo da subconta depois dele. Veja Webhooks de subcontas.

​

Saque da subconta para o cliente

POST /v1/subaccounts/{id}/withdrawals · escopo withdrawals:write · Idempotency-Key obrigatória

{ "amount": 10000, "destination": { "keyType": "email", "key": "[e-mail]" }, "description": "Repasse semanal" }

É um saque normal (SAQ-API-), com as mesmas regras do saque. O Pix vai para a chave enviada em destination ou, sem ela, para a pixKey guardada na subconta (sem nenhuma das duas: DESTINATION_REQUIRED). amount sai da subconta; a sua taxa por saque paga a tarifa da WyzeCash e o que sobra fica com você; se a sua taxa não cobre a tarifa, ela sai do valor sacado. Se não sobrar nada para o cliente: FEE_ABOVE_AMOUNT. Subconta desativada não saca. Falhou ou foi recusado, o valor volta à subconta. A resposta e os webhooks são os do saque.