> ## 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.

# Criar subconta

> Cria uma subconta (sacc_) para um cliente seu, com comissão por venda, taxa por saque e a chave Pix dele.

Escopo `subaccounts:write`. O dinheiro continua no seu saldo; a subconta guarda quanto dele é atribuído ao cliente. Cobranças e links criados com `subaccountId` (ou com `split`) creditam a venda a ela quando pagos. Em toda rota com `{id}` vale o `sacc_...` ou o seu `externalId`.

**name** `string` *required*

Hoje: 2 a 80 caracteres (`INVALID_NAME`). Veja a [regra do nome](#regra-do-nome-vai-passar-a-valer), que vai passar a valer.

**email** `string | null`

E-mail do cliente, guardado criptografado. A lista mostra só `hasEmail`; o detalhe mostra o e-mail.

**externalId** `string | null`

O identificador do cliente no seu sistema: letras, números, ponto, hífen e sublinhado, até 64, e sem o formato `sacc_` (`INVALID_EXTERNAL_ID`). Único por conta (`409 EXTERNAL_ID_IN_USE`); volta a ficar livre quando a subconta é excluída.

**document** `string | null`

CPF ou CNPJ do titular, com ou sem pontuação: conferido pelos dígitos (`422 INVALID_DOCUMENT`) e guardado criptografado. Sempre inteiro (mascarado é recusado). Vem inteiro no detalhe e mascarado na lista.

**saleFeeBps** `integer`

Sua comissão por venda em pontos-base: 100 = 1%, de 0 a 10000.

**saleFeeFixed** `integer`

Parte fixa da comissão por venda, em centavos (até 1.000.000).

**withdrawFeeBps** `integer`

Sua taxa por saque da subconta, em pontos-base. Ela paga a tarifa da WyzeCash do saque; o que sobra fica com você.

**withdrawFeeFixed** `integer`

Parte fixa da taxa por saque, em centavos.

**feeMode** `"global" | "custom"`

`global` segue a taxa global da [Configuração das subcontas](https://docs.wyzecash.com.br/referencia/subcontas/configuracao-das-subcontas.md); `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. Os `limits` que não vierem usam os limites padrão da Configuração.

**metadata** `object | null`

Objeto JSON livre para os seus dados (até 2 KB, `422 INVALID_METADATA`). Volta no detalhe.

**pixKey** `object | null`

`{ "keyType": "cpf" | "cnpj" | "email" | "phone" | "random", "key": "..." }`: a chave Pix do cliente, conferida na hora (titular e banco) e guardada criptografada. É o destino padrão do [saque da subconta](https://docs.wyzecash.com.br/referencia/subcontas/saque-da-subconta.md) quando o pedido não manda `destination`. Chave de conta WyzeCash: `422 INTERNAL_ACCOUNT`.

## Regra do nome (vai passar a valer)

> [!WARNING]
>
> **Ainda não vale.** Hoje a API aceita qualquer nome de 2 a 80 caracteres. A WyzeCash avisa antes de ligar a regra: ajuste a sua integração desde já.

Quando a regra for ligada, o `name` segue o documento do titular (`document`):

| Titular | O nome é | Exemplo |
| - | - | - |
| CPF | o nome completo: nome e sobrenome, só letras (com acento), espaço, `'`, `-` e `.` | `Ana Souza` |
| CNPJ | a razão social: pelo menos uma letra; letras, números, espaço e `. , - & / '` | `Ateliê da Ana Ltda` |
| sem `document` | um dos dois | `Ana Souza` |

Até 100 caracteres. **Nunca** o CPF ou CNPJ (inteiro ou mascarado) nem um id entre colchetes no nome, como `Ana Souza 123.456.789-00` ou `[bot:8812] Ana Souza`: o CPF/CNPJ vai em `document` e o id do seu sistema em `externalId`.

Fora da regra, a API vai responder `422 INVALID_NAME` ao criar e ao trocar o nome (mandar de novo o mesmo nome que já está salvo continua passando). As mensagens:

| Quando | Mensagem |
| - | - |
| CPF ou CNPJ no nome | Não coloque CPF ou CNPJ no nome: use o campo document do titular. |
| id ou colchetes no nome | Não coloque colchetes nem ids no nome: use o externalId. |
| os dois | Não coloque CPF, CNPJ nem ids no nome: use os campos document (CPF/CNPJ do titular) e externalId. |
| titular com CPF e nome sem sobrenome | Informe o nome do cliente. |

## Resposta

**id** `string`

`sacc_` + 32 hex.

**name** `string`

Nome.

**externalId** `string | null`

Seu identificador.

**hasEmail** `boolean`

Se há e-mail guardado.

**email** `string | null`

O e-mail (só no detalhe: criar, consultar e editar).

**feeMode** `string`

`global` (as taxas vêm da Configuração das subcontas) ou `custom` (as dela).

**saleFee** `object`

`{ percentBps, fixed }`: comissão por venda que vale.

**withdrawFee** `object`

`{ percentBps, fixed }`: taxa por saque.

**balance** `integer`

Saldo atribuído à subconta (centavos), nunca negativo.

**active** `boolean`

Ativa ou desativada.

**medLocked** `boolean`

Bloqueada pelo bloqueio automático por MED: o saque fica trancado até a pendência acabar.

**medPending** `integer`

Pendência do MED (centavos): o que falta reservar dos MED abertos mais o que ficou devendo dos devolvidos. Sai das próximas entradas dela.

**pixKey** `object | null`

`{ keyType, key, holderName, institution }`; `null` sem chave. A chave vem inteira no detalhe (criar, consultar e editar) e mascarada na lista.

**metadata** `object | null`

Os seus dados (só no detalhe).

**createdAt** `string`

Criação.

```bash cURL 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",
    "email": "ana@exemplo.com",
    "saleFeeBps": 500,
    "withdrawFeeFixed": 200,
    "pixKey": { "keyType": "cpf", "key": "123.456.789-00" },
    "metadata": { "plano": "pro" }
  }'
```

```json 200 theme={null}
{
  "id": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f",
  "name": "Ateliê da Ana",
  "externalId": "vendedor-42",
  "hasEmail": true,
  "email": "ana@exemplo.com",
  "feeMode": "custom",
  "saleFee": { "percentBps": 500, "fixed": 0 },
  "withdrawFee": { "percentBps": 0, "fixed": 200 },
  "balance": 0,
  "active": true,
  "medLocked": false,
  "medPending": 0,
  "pixKey": { "keyType": "cpf", "key": "123.456.789-00", "holderName": "Ana S.", "institution": "Banco Exemplo" },
  "metadata": { "plano": "pro" },
  "createdAt": "2026-10-08T15:00:00.000Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.