> ## Documentation Index
> Fetch the complete documentation index at: https://docs.purincash.com/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](/guias/subcontas) avisam as **URLs da conta**, configuradas em
[Dashboard → Equipe & API → Developer API](https://purincash.com/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`](/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.
</Note>

<CodeGroup>
  ```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"
  }
  ```
</CodeGroup>

## Campos

<ResponseField name="event" type="string" required>
  `subaccount.transfer`, `subaccount.payout` ou `subaccount.payout_reversal`.
</ResponseField>

<ResponseField name="subaccountId" type="string" required>
  A subconta movimentada.
</ResponseField>

<ResponseField name="amountCents" type="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).
</ResponseField>

<ResponseField name="transferId" type="string">
  Só em `subaccount.transfer`. É o mesmo `refId` do extrato (`tr_` ou `idem_`).
</ResponseField>

<ResponseField name="direction" type="string">
  Só em `subaccount.transfer`: `to_master` ou `to_subaccount`.
</ResponseField>

<ResponseField name="balanceCents" type="integer">
  Só em `subaccount.transfer`: saldo da subconta logo após o movimento.
</ResponseField>

<ResponseField name="origin" type="string">
  Só em `subaccount.transfer`: `api` ou `panel`. É como você descobre que o dono
  da loja moveu saldo pelo painel.
</ResponseField>

<ResponseField name="code" type="string">
  Nos eventos de saque: o código do saque, o mesmo que aparece em `GET /v1/payouts`
  e no extrato da subconta.
</ResponseField>

<ResponseField name="status" type="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.
</ResponseField>

<ResponseField name="reason" type="string">
  Só em `subaccount.payout_reversal`: motivo interno do estorno.
</ResponseField>

<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.
</Warning>

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.