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

# Payouts

> Ciclos de pagamento: prévia, execução, retentativa, cancelamento e recibos.

`repass.payouts` gerencia os ciclos de [payout](/docs/conceitos/payouts), agregando comissões aprovadas em pagamentos por afiliado, com prévia, execução, retentativa e recibos.

## Consulta

`retrieve` aceita `expand: ["commissions"]` para trazer as comissões que compõem o payout.

```ts theme={null}
// Listar (RepassPage, filtros opcionais por status e método)
await repass.payouts.list({ status: "paid", method: "pix" }); // → RepassPage<Payout>

// Buscar (com as comissões agregadas)
await repass.payouts.retrieve("pay_…", { expand: ["commissions"] }); // → ExpandedPayout (Payout + commissions quando expandido)
```

## Prévia e execução

`preview` e `run` têm efeito pesado sobre o ciclo. **Sempre passe `idempotencyKey`** (veja [Configuração](/docs/sdk/configuracao)) para que retentativas não dupliquem o processamento.

```ts theme={null}
// Prévia do ciclo (não cria payouts)
await repass.payouts.preview({ /* filtros do ciclo */ }); // → PayoutPreviewResult ({ eligible, blocked, totals })

// Executa o ciclo
await repass.payouts.run({ /* … */ }, { idempotencyKey: "run-2026-06" }); // → PayoutRunResult ({ eligible, blocked, totals, dryRun, payouts })
```

Cada elegível da prévia/execução traz `destination` (chave PIX/método atual do afiliado). A execução real (`dryRun: false`) agrupa os payouts num **lote** de fechamento. Veja [`repass.payoutBatches`](/docs/sdk/recursos/payout-batches).

## Relatório contábil

`accountingReport` retorna a visão contábil dos payouts liquidados num período (por data de pagamento), base para exportar o CSV.

```ts theme={null}
await repass.payouts.accountingReport({
  from: "2026-06-01T00:00:00.000Z",
  to: "2026-07-01T00:00:00.000Z",
}); // → PayoutAccountingReport ({ from, to, entries, totals })
```

## Retentativa e cancelamento

```ts theme={null}
await repass.payouts.retry("pay_…");  // → Payout (re-tenta um payout que falhou)
await repass.payouts.cancel("pay_…"); // → Payout (cancela um payout pendente)
```

## Recibos

`receipt` retorna a URL do comprovante emitido pelo provedor de pagamento.

```ts theme={null}
await repass.payouts.receipt("pay_…"); // → PayoutReceipt ({ payoutId, providerReceiptUrl })
```

<Note>
  Para o schema completo de cada corpo (filtros do ciclo, formato de `totals`, status e métodos) e os campos de cada objeto retornado, consulte a [Referência da API](/docs/convencoes/ids-e-recursos). As regras de negócio estão em [Payouts](/docs/conceitos/payouts).
</Note>