Editar subconta

Muda nome, e-mail, identificador, comissão, taxa por saque, metadata, chave Pix, ou ativa e desativa.

PATCH /v1/subaccounts/{id}

cURL

curl -X PATCH https://bukio-backend-production.up.railway.app/v1/subaccounts/vendedor-42 \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "saleFeeBps": 800, "pixKey": { "keyType": "cpf", "key": "123.456.789-00" } }'

200

{
  "id": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f",
  "name": "Ateliê da Ana",
  "externalId": "vendedor-42",
  "hasEmail": true,
  "email": "[e-mail]",
  "saleFee": { "percentBps": 800, "fixed": 0 },
  "withdrawFee": { "percentBps": 0, "fixed": 200 },
  "balance": 14200,
  "active": true,
  "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. Todos os campos são opcionais; só os enviados mudam.

Subconta desativada (active: false): a venda de uma cobrança ligada a ela fica com você (não é creditada), e ela não recebe envio, transferência nem saque (422 SUBACCOUNT_INACTIVE). O saldo atribuído fica guardado e dá para devolver à principal. active: true reativa.

id · string · required

sacc_ + 32 hex ou o seu externalId.

name · string

Hoje: 2 a 80 caracteres. A regra do nome (nome do titular, sem CPF/CNPJ nem id) vai passar a valer também aqui; mandar o mesmo nome que já está salvo continua passando.

email · string | null

E-mail; null apaga.

externalId · string | null

Seu identificador; null apaga. Já usado por outra: 409 EXTERNAL_ID_IN_USE.

saleFeeBps · integer

Comissão por venda em pontos-base. Vale para as próximas vendas.

saleFeeFixed · integer

Parte fixa da comissão (centavos).

withdrawFeeBps · integer

Taxa por saque em pontos-base.

withdrawFeeFixed · integer

Parte fixa da taxa por saque (centavos).

feeMode · "global" | "custom"

global volta a seguir a taxa global da Configuração das subcontas. Mandar qualquer taxa acima deixa a subconta com a própria (custom).

metadata · object | null

Objeto JSON livre, até 2 KB (422 INVALID_METADATA). Substitui o anterior; null apaga.

pixKey · object | null

{ "keyType", "key" }: a chave Pix do cliente, conferida na hora (titular e banco). Vira o destino padrão do saque da subconta. Chave de conta WyzeCash: 422 INTERNAL_ACCOUNT. null apaga. Toda troca fica registrada e você recebe um aviso de segurança.

active · boolean

false desativa; true reativa.

​

Resposta

A subconta atualizada, no formato de Consultar subconta.

cURL

curl -X PATCH https://bukio-backend-production.up.railway.app/v1/subaccounts/vendedor-42 \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "saleFeeBps": 800, "pixKey": { "keyType": "cpf", "key": "123.456.789-00" } }'

200

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