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

> subaccount.credited e subaccount.debited: cada movimento SUB- que muda o saldo de uma subconta.

Toda vez que o saldo atribuído a uma [subconta](https://docs.wyzecash.com.br/endpoints/subcontas.md) 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

```json theme={null}
{
  "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}`).


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