> ## Documentation Index > Fetch the complete documentation index at: https://docs.wyzecash.com.br/llms.txt > Use this file to discover all available pages before exploring further. # 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`](https://docs.wyzecash.com.br/referencia/subcontas/criar-subconta) · 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](https://docs.wyzecash.com.br/referencia/subcontas/criar-subconta.md#regra-do-nome-vai-passar-a-valer). **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](#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. ```bash theme={null} curl -X POST https://api.wyzecash.com.br/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": "ana@example.com" }, "metadata": { "plano": "pro" } }' ``` ```json theme={null} { "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": "ana@example.com", "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](https://docs.wyzecash.com.br/referencia/subcontas/editar-subconta.md) | `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`](https://docs.wyzecash.com.br/referencia/subcontas/configuracao-das-subcontas) | `subaccounts:get` | a taxa global, os limites padrão e o bloqueio automático por MED | | PUT | [`/v1/subaccounts/settings`](https://docs.wyzecash.com.br/referencia/subcontas/mudar-configuracao) | `subaccounts:update` | muda o que vier no pedido | | GET | [`/v1/subaccounts/settings/preview`](https://docs.wyzecash.com.br/referencia/subcontas/exemplo-da-configuracao) | `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](https://docs.wyzecash.com.br/referencia/subcontas/mudar-configuracao.md). ## Listar, ver e alterar | Método | Rota | Escopo | O que faz | | - | - | - | - | | GET | [`/v1/subaccounts?limit=&cursor=`](https://docs.wyzecash.com.br/referencia/subcontas/listar-subcontas) | `transactions:read` | subcontas com saldo atribuído e o total atribuído | | GET | [`/v1/subaccounts/{id}`](https://docs.wyzecash.com.br/referencia/subcontas/consultar-subconta) | `transactions:read` | uma subconta | | PATCH | [`/v1/subaccounts/{id}`](https://docs.wyzecash.com.br/referencia/subcontas/editar-subconta) | `subaccounts:write` | mesmos campos (todos opcionais; `null` apaga `pixKey` e `metadata`) e `active` para ativar ou desativar | | DELETE | [`/v1/subaccounts/{id}`](https://docs.wyzecash.com.br/referencia/subcontas/excluir-subconta) | `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=`](https://docs.wyzecash.com.br/referencia/subcontas/movimentos-da-subconta) · 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). ```json theme={null} { "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`](https://docs.wyzecash.com.br/referencia/subcontas/enviar-para-subconta) | `{ 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`](https://docs.wyzecash.com.br/referencia/subcontas/transferir-entre-subcontas) | `{ to, amount, description? }` | passa saldo para outra subconta sua (`to`: `sacc_...` ou `externalId`); as duas ativas e diferentes | | POST | [`/v1/subaccounts/{id}/return`](https://docs.wyzecash.com.br/referencia/subcontas/devolver-a-principal) | `{ amount, description? }` | devolve à sua conta principal (vale com a subconta desativada) | ```json theme={null} { "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}`](https://docs.wyzecash.com.br/referencia/subcontas/excluir-subconta) · 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. ```json theme={null} { "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](https://docs.wyzecash.com.br/referencia/cobrancas/criar-cobranca.md), `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ê. ```json theme={null} { "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](https://docs.wyzecash.com.br/referencia/links-de-pagamento/criar-link.md) 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](https://docs.wyzecash.com.br/webhooks/subcontas.md). ## Saque da subconta para o cliente [`POST /v1/subaccounts/{id}/withdrawals`](https://docs.wyzecash.com.br/referencia/subcontas/saque-da-subconta) · escopo `withdrawals:write` · `Idempotency-Key` obrigatória ```json theme={null} { "amount": 10000, "destination": { "keyType": "email", "key": "ana@example.com" }, "description": "Repasse semanal" } ``` É um saque normal (`SAQ-API-`), com as mesmas regras do [saque](https://docs.wyzecash.com.br/endpoints/saques.md). 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.