Subcontas - API WyzeCash

Toda vez que o saldo atribuído a uma subconta muda, a WyzeCash manda um evento com o movimento SUB- e o saldo dela depois. Assim o seu sistema mantém o saldo de cada cliente sem ficar consultando a API.

Evento	Quando
`subaccount.credited`	entrou na subconta: venda creditada (`sale`), envio da conta principal (`fund`) ou transferência recebida de outra subconta (`transfer`)
`subaccount.debited`	saiu da subconta: saque para o cliente (`withdraw`), devolvido à principal (`return`), transferência para outra subconta (`transfer`), estorno de venda (`refund`), devolução MED (`med`) ou ajuste (`adjust`)

Uma transferência entre subcontas gera dois eventos: subaccount.debited na origem e subaccount.credited no destino. Um saque da subconta que falhar devolve o valor com um subaccount.credited de kind: "withdraw".

Corpo

{
  "id": "evt_01JA7XM3P5R7T9V1X3Z5B7D9F1",
  "type": "subaccount.credited",
  "created_at": "2026-10-08T15:04:12.502Z",
  "data": {
    "id": "SUB-2W8M4Z3F7K9Q",
    "subaccountId": "sacc_9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f",
    "externalId": "vendedor-42",
    "kind": "sale",
    "kindTitle": "Venda creditada",
    "direction": "credit",
    "amount": 14200,
    "fee": 800,
    "balance": 28400,
    "description": "Cobrança BKY-7KQ2M9XP4RZT · Pedido 1842",
    "reference": "BKY-7KQ2M9XP4RZT",
    "createdAt": "2026-10-08T15:04:12.000Z"
  }
}

Campo	O que é
`id`	o movimento (`SUB-` + 12)
`subaccountId`	a subconta (`sacc_...`)
`externalId`	o seu identificador da subconta, ou `null`
`kind` / `kindTitle`	o tipo do movimento, em código e em português
`direction`	`credit` ou `debit`
`amount`	o que entrou ou saiu da subconta (centavos)
`fee`	na venda: a tarifa da WyzeCash mais a sua comissão; no saque: o que não foi para a chave do cliente (a sua taxa por saque, ou a tarifa se ela for maior); `0` ou `null` nos outros
`balance`	saldo da subconta depois do movimento
`description`	descrição do movimento
`reference`	o código de origem, quando há: a cobrança (`BKY-`), o saque (`SAQ-`), o estorno (`EST-`) ou o MED (`MED-`)

O jeito certo de tratar

Use balance como o saldo atual da subconta, mas confira a ordem pelo createdAt: eventos podem chegar fora de ordem. Em dúvida, GET /v1/subaccounts/{id} é a verdade.
Dedupe pelo id do evento (evt_...), não pelo SUB-: uma reentrega repete o mesmo evt_.
Para o detalhe da venda, consulte a cobrança pelo reference (GET /v1/payments/{id}).