subaccount.* - PurinCash

Movimentos de subconta avisam as URLs da conta, configuradas em Dashboard → Equipe & API → Developer 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, que carrega o subaccountId.

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.

{
  "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"
}

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

{
  "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

string

required

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

string

required

A subconta movimentada.

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).

string

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

string

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

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.

integer

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

integer

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

string

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

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}.

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.

string

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

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.