Criar subconta

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

POST /v1/subaccounts

cURL

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",
    "email": "[e-mail]",
    "saleFeeBps": 500,
    "withdrawFeeFixed": 200,
    "pixKey": { "keyType": "cpf", "key": "123.456.789-00" },
    "metadata": { "plano": "pro" }
  }'

200

{
  "id": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f",
  "name": "Ateliê da Ana",
  "externalId": "vendedor-42",
  "hasEmail": true,
  "email": "[e-mail]",
  "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"
}

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, 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; 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 quando o pedido não manda destination. Chave de conta WyzeCash: 422 INTERNAL_ACCOUNT.

​

Regra do nome (vai passar a valer)

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.

cURL

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",
    "email": "[e-mail]",
    "saleFeeBps": 500,
    "withdrawFeeFixed": 200,
    "pixKey": { "keyType": "cpf", "key": "123.456.789-00" },
    "metadata": { "plano": "pro" }
  }'

200

{
  "id": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f",
  "name": "Ateliê da Ana",
  "externalId": "vendedor-42",
  "hasEmail": true,
  "email": "[e-mail]",
  "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"
}