> ## Documentation Index
> Fetch the complete documentation index at: https://docs.purin.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# subaccount.*

> Transferência, saque e estorno: todo movimento do ledger que não nasce de uma cobrança.

Movimentos de [subconta](https://docs.purin.cash/guias/subcontas.md) avisam as **URLs da conta**, configuradas em
[Dashboard → Equipe & API → Developer API](https://purin.cash/dashboard/api).
Vale para movimentos feitos pela API **e pelo painel**: uma transferência manual do
dono da loja chega no seu sistema do mesmo jeito.

| Evento | Quando |
| - | - |
| `subaccount.transfer` | Transferência entre a subconta e a conta principal, nos dois sentidos |
| `subaccount.payout` | Saque turbo debitando a subconta saiu (ou pode ter saído e está em revisão) |
| `subaccount.payout_reversal` | O banco negou o saque e a atribuição voltou pra subconta |

A venda **não** ganha evento próprio aqui: ela já avisa pelo
[`charge.paid`/`payment.paid`](https://docs.purin.cash/webhooks/pagamentos), que carrega o `subaccountId`.

> [!NOTE]
>
> Sandbox não emite eventos de subconta. Evento de teste caindo na URL de produção
> confundiria mais do que ajudaria: valide o fluxo com o extrato
> (`GET /v1/subaccounts/{id}/transactions`), que funciona igual nos dois ambientes.

```json Transferência theme={null}
{
  "event": "subaccount.transfer",
  "id": "tr_1a2b3c4d5e6f7a8b9c0d1e2f",
  "subaccountId": "sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "transferId": "tr_1a2b3c4d5e6f7a8b9c0d1e2f",
  "direction": "to_master",
  "amountCents": 30000,
  "balanceCents": 15900,
  "description": "Comissão da plataforma",
  "origin": "panel",
  "createdAt": "2026-08-05T14:00:00.000Z"
}
```

```json Saque theme={null}
{
  "event": "subaccount.payout",
  "id": "TURBO-A1B2C3D4",
  "subaccountId": "sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "code": "TURBO-A1B2C3D4",
  "amountCents": 50000,
  "status": "completed",
  "createdAt": "2026-08-05T14:05:00.000Z"
}
```

```json Estorno theme={null}
{
  "event": "subaccount.payout_reversal",
  "id": "TURBO-A1B2C3D4",
  "subaccountId": "sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "code": "TURBO-A1B2C3D4",
  "amountCents": 50000,
  "reason": "banco_recusou",
  "createdAt": "2026-08-05T14:06:00.000Z"
}
```

## Campos

**event** `string` *required*

`subaccount.transfer`, `subaccount.payout` ou `subaccount.payout_reversal`.

**subaccountId** `string` *required*

A subconta movimentada.

**amountCents** `integer` *required*

Valor do movimento em centavos, sempre positivo. O sentido vem de `direction`
(transferência) ou do próprio tipo de evento (saque debita, estorno credita).

**transferId** `string`

Só em `subaccount.transfer`. É o mesmo `refId` do extrato (`tr_` ou `idem_`).

**direction** `string`

Só em `subaccount.transfer`: `to_master`, `to_subaccount` ou `between_subaccounts`.

**toSubaccountId** `string`

Só em `subaccount.transfer` com `between_subaccounts`: a subconta que recebeu. O
`subaccountId` do evento é a origem, e é enviado um único evento por transferência.

**toBalanceCents** `integer`

Só em `between_subaccounts`: saldo da subconta de destino logo após o movimento.

**balanceCents** `integer`

Só em `subaccount.transfer`: saldo da subconta logo após o movimento.

**origin** `string`

Só em `subaccount.transfer`: `api` ou `panel`. É como você descobre que o dono
da loja moveu saldo pelo painel.

**code** `string`

Nos eventos de saque: o código do saque, o mesmo que aparece em `GET /v1/payouts`
e no extrato da subconta. É com ele que você consulta o saque a qualquer momento, em
`GET /v1/subaccounts/{id}/payouts/{code}`.

**status** `string`

Só em `subaccount.payout`: `completed` (banco confirmou) ou `processing` (o PIX
saiu ou pode ter saído; a confirmação vem depois). Nos dois casos o débito no
ledger FICA: não trate `processing` como falha.

**reason** `string`

Só em `subaccount.payout_reversal`: motivo interno do estorno.

> [!WARNING]
>
> `subaccount.payout` com `status: "processing"` seguido de
> `subaccount.payout_reversal` com o mesmo `code` é o ciclo completo de um saque que
> o banco acabou negando: o débito aconteceu, depois voltou. Espelhe os dois no seu
> ledger em vez de ignorar o primeiro.

As garantias são as mesmas dos outros eventos: assinatura HMAC em
`X-Webhook-Signature`, idempotência em `X-Webhook-Id` (formato `evento:id`) e
reentrega com backoff.


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