Payouts

Um Payout (repasse) agrega todas as Comissões aprovadas e não pagas de um Afiliado em um único pagamento, valida elegibilidade (perfil fiscal completo, sem fraude em aberto, sem nota fiscal pendente, saldo acima do mínimo), agenda e executa via provedor PIX. Cada payout é um fato financeiro independente, com snapshot congelado do destino (chave PIX) no momento da criação, e marca atomicamente todas as comissões incluídas como pagas quando liquidado. O ciclo tem dois passos distintos:

Fechamento: POST /payouts/run, manual, com dry-run por padrão. Cria os payouts scheduled e reserva as comissões.
Execução: liquida os payouts scheduled via PIX, em lote.

IDs de payout usam o prefixo pay_ (ULID): pay_01J9X.... Valores monetários são sempre inteiros em centavos (amountCents) na moeda BRL.

Ciclo de vida

Um payout nasce scheduled no fechamento, é promovido a processing quando a execução inicia e termina em completed ou failed. O operador pode cancelar (scheduled) ou reagendar (failed).

Status	Significado
`scheduled`	Criado e reservou as comissões; aguarda execução. Estado inicial.
`processing`	Execução iniciada (pagamento PIX em andamento).
`completed`	Pagamento liquidado; comissões marcadas `paid`. Terminal.
`failed`	Execução falhou; razão registrada em `failureReason`. Pode voltar a `scheduled` via retry.
`canceled`	Fechamento desfeito; comissões liberadas. Terminal.

Um payout só pode ser cancelado enquanto está scheduled. Se a execução já o tiver promovido para processing, o cancel falha com 409. Isso evita que um cancelamento aconteça depois que o pagamento já começou.

Fechamento de ciclo

O fechamento agrega o saldo de cada afiliado e decide quem é elegível. Use POST /payouts/preview (ou POST /payouts/run com dryRun: true) para inspecionar o resultado sem persistir nada. As duas chamadas retornam exatamente o mesmo resumo. Para efetivar, chame POST /payouts/run com dryRun: false.

dryRun tem default true. Um POST /payouts/run sem corpo (ou sem dryRun) não cria payouts: apenas calcula a prévia. Você precisa enviar dryRun: false explicitamente para fechar o ciclo.

Cada elegível da prévia traz também destination (chave PIX/método atual do afiliado), para você conferir “quem recebe onde” antes de efetivar.

Lote do fechamento (histórico de ciclos)

Um fechamento real cria um lote (payout_batch, prefixo cyc_) que agrupa os payouts daquele run. É o histórico de ciclos: liste com GET /payout-batches e abra um com GET /payout-batches/:id (expand=payouts,invoices). O status do lote é derivado dos payouts-membro: processing enquanto algum estiver agendado/processando, completed quando todos liquidam, partial se houver falha/cancelamento. Para a contabilidade, GET /payouts/accounting-report?from=…&to=… devolve uma linha por payout liquidado no período (afiliado, valor, comprovante, situação da NF).

Agregação líquida

O payout soma todas as comissões approved, sem payout associado e fora de revisão de fraude, incluindo clawbacks (comissões negativas). O amountCents é o líquido e precisa ser > 0 para o payout ser criado.

Cenário	Resultado
Comissão `9000` + clawback `-1000`	Payout de `8000`, `commissionCount: 2`
Saldo `< minimumPayoutCents` (default `5000`)	Bloqueado `below_minimum`, acumula para o próximo ciclo
Saldo `<= 0` (clawbacks ≥ comissões)	Bloqueado `non_positive_balance`, débito rola para ciclos futuros

curl https://api.userepass.com/payouts/preview \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -d '{ "programId": "prog_01J9X..." }'

curl https://api.userepass.com/payouts/run \
  -H "Authorization: Bearer rstr_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-2026-06-13" \
  -d '{ "dryRun": false }'

Resposta (run dryRun=false)

{
  "dryRun": false,
  "totals": { "eligibleAmountCents": 23000, "eligibleCount": 2, "blockedCount": 1 },
  "eligible": [
    {
      "affiliateId": "aff_01J9X...",
      "affiliateName": "Maria Silva",
      "method": "pix",
      "amountCents": 8000,
      "commissionCount": 2
    }
  ],
  "blocked": [
    {
      "affiliateId": "aff_01J9Y...",
      "affiliateName": "João Souza",
      "reason": "below_minimum",
      "amountCents": 3200,
      "commissionCount": 1
    }
  ],
  "payouts": [
    {
      "id": "pay_01J9Z...",
      "affiliateId": "aff_01J9X...",
      "status": "scheduled",
      "method": "pix",
      "amountCents": 8000,
      "commissionCount": 2
    }
  ]
}

O body de preview e run aceita programId opcional para restringir o fechamento aos afiliados de um único Programa. Sem ele, o ciclo cobre toda a organização.

Threshold mínimo e política

A política de payout fica na configuração da organização, consultável em GET /settings/payout-policy e ajustável via PUT /settings/payout-policy (vale para os próximos ciclos).

string

default:"monthly"

monthly, biweekly ou manual. Hoje serve como configuração de referência: o fechamento é sempre disparado manualmente via POST /payouts/run.

integer

default:"1"

Dia de fechamento (1 a 28). Também serve como configuração de referência.

integer

default:"5000"

Valor mínimo de saque em centavos. Saldo abaixo disso bloqueia com below_minimum e acumula para o próximo ciclo. Default 5000 (R$ 50,00).

string

default:"pix"

Método de pagamento padrão sugerido para novos afiliados.

Reserva (sem dupla cobrança)

No fechamento real, a criação de cada payout reserva as comissões incluídas. Se alguma comissão deixou de ser pagável entre o cálculo e a criação (refund, ban, outro run concorrente), o fechamento é abortado com 409 conflict. Basta re-rodar. Reexecutar o run não duplica: comissões já reservadas saem do conjunto pagável, então um segundo run não encontra nada elegível.

Bloqueios

Um afiliado é excluído do ciclo (aparece em blocked, sem payout criado) por um destes motivos:

`reason`	Condição
`banned`	Afiliado com status `banned`.
`incomplete_payout_profile`	Sem `pixKey`, ou (NF exigida) sem `cnpj`.
`fraud_review_open`	Existe revisão de fraude aberta para o afiliado.
`pending_invoice`	NF exigida tem nota de payout anterior não resolvida (pendente/rejeitada).
`non_positive_balance`	Saldo `<= 0` (clawbacks ≥ comissões).
`below_minimum`	Saldo abaixo de `minimumPayoutCents`.

A nota fiscal do próprio ciclo nunca se bloqueia: o cálculo de elegibilidade roda antes da criação da invoice, então só NFs de payouts anteriores não resolvidas geram pending_invoice. NF cancelada (junto com o payout) não conta como pendência.

Snapshot do destino

No fechamento, o payout congela o destination: { method, pixKey?, pixKeyType? }, copiado do perfil do afiliado. Trocar a chave PIX do afiliado depois não afeta payouts já criados. Os métodos pix, bank_transfer, wise e paypal são aceitos e congelados no snapshot; atualmente, apenas PIX tem caminho de liquidação disponível.

Nota fiscal antes do pagamento

Quando a política fiscal exige NF (nfMode: "affiliate_uploads"), o fechamento cria uma invoice pending junto do payout, e a execução só liquida depois que a NF fica validated. Enquanto a NF não é validada, a execução pula o payout (permanece scheduled). Veja Fiscal para o detalhe da política nfMode, do upload e da validação da NF.

Execução em lote (PIX)

A execução processa os payouts scheduled em lote. Para cada payout liquidado, marca todas as comissões incluídas como paid, com um paidAt único.

Uma falha (failed) mantém as comissões reservadas (associadas ao payout, não pagas, não liberadas) até um retry ou cancel. Não há cobrança ao afiliado em saldo não positivo: o débito rola para o próximo ciclo.

Operações do payout

Todas as rotas exigem autenticação via API key (Authorization: Bearer rstr_...). As operações que mudam estado (run, retry, cancel e o PUT /settings/payout-policy) exigem papel owner ou admin; preview, listagens e detalhe estão abertos a qualquer membro. As rotas POST aceitam Idempotency-Key (replays retornam a resposta armazenada com Idempotent-Replay: true).

Listar e inspecionar

GET /payouts lista com paginação por cursor e filtros affiliate_id, status, method. GET /payouts/:payoutId traz o detalhe e aceita expand[]=commissions (anexa até 100 comissões do payout).

Cancelar

POST /payouts/:payoutId/cancel só é permitido em scheduled. Libera as comissões (voltam a approved não pago) e cancela a invoice associada. Qualquer outro estado retorna 409 conflict.

Reagendar

POST /payouts/:payoutId/retry só é permitido em failed. Limpa failureReason/failedAt e repõe o status scheduled para uma nova tentativa de liquidação. O retry é sempre disparado manualmente.

Comprovante

GET /payouts/:payoutId/receipt retorna o comprovante do provedor apenas quando o payout está completed e há providerReceiptUrl; caso contrário, 404 resource_not_found.

curl "https://api.userepass.com/payouts?status=scheduled&limit=20" \
  -H "Authorization: Bearer rstr_..."

curl -X POST https://api.userepass.com/payouts/pay_01J9Z.../cancel \
  -H "Authorization: Bearer rstr_..."

curl -X POST https://api.userepass.com/payouts/pay_01J9Z.../retry \
  -H "Authorization: Bearer rstr_..."

curl https://api.userepass.com/payouts/pay_01J9Z.../receipt \
  -H "Authorization: Bearer rstr_..."

Para os campos completos de requisição e resposta de cada endpoint, veja a aba Referência da API.

Erros comuns

Situação	HTTP	`code`
Payout inexistente	404	`resource_not_found`
Comprovante ausente (não `completed` ou sem URL)	404	`resource_not_found`
Cancelar payout não `scheduled`	409	`conflict`
Retry de payout não `failed`	409	`conflict`
Comissões deixaram de ser pagáveis durante o run	409	`conflict`
Body/query inválidos	400	`parameter_invalid`

Veja o envelope completo em Erros.

Eventos de domínio

Cada mudança de estado emite eventos. O ciclo completo gera, na ordem:

Evento	Quando
`payout.created`	Fechamento real cria o payout. Payload inclui `commissionIds[]`.
`invoice.created`	Junto do `payout.created`, quando a NF é exigida (`nfMode: "affiliate_uploads"`).
`payout.processing`	A execução do pagamento inicia.
`payout.completed`	O pagamento PIX é confirmado.
`commission.paid`	Junto do `payout.completed`, uma por comissão paga.
`payout.failed`	O pagamento PIX retorna erro (payload com `reason`).
`payout.retried`	Operador reenfileira payout `failed`.
`payout.canceled`	Operador cancela payout `scheduled` (payload com `commissionIds[]` liberadas).
`invoice.canceled`	Junto do `payout.canceled`, se havia invoice.
`settings.updated`	`PUT /settings/payout-policy` altera a política.

Assine esses eventos via Webhooks ou consulte o histórico no Event store.

Próximos passos

Comissões

O que entra no saldo de um payout e como clawbacks afetam o líquido.

Fiscal

Política nfMode, upload de NF e o gate de validação antes da liquidação.

Refund e clawback

Como estornos reduzem o saldo a pagar nos próximos ciclos.

Catálogo de eventos

Payloads dos eventos payout.* e commission.paid.

Introdução

Convenções da API

Conceitos

Webhooks & Eventos

Guias

Ciclo de vida

Fechamento de ciclo

Lote do fechamento (histórico de ciclos)

Agregação líquida

Threshold mínimo e política

Reserva (sem dupla cobrança)

Bloqueios

Snapshot do destino

Nota fiscal antes do pagamento

Execução em lote (PIX)

Operações do payout

Erros comuns

Eventos de domínio

Próximos passos

Comissões

Fiscal

Refund e clawback

Catálogo de eventos

​Ciclo de vida

​Fechamento de ciclo

​Lote do fechamento (histórico de ciclos)

​Agregação líquida

​Threshold mínimo e política

​Reserva (sem dupla cobrança)

​Bloqueios

​Snapshot do destino

​Nota fiscal antes do pagamento

​Execução em lote (PIX)

​Operações do payout

​Erros comuns

​Eventos de domínio

​Próximos passos

Comissões

Fiscal

Refund e clawback

Catálogo de eventos

Ciclo de vida

Fechamento de ciclo

Lote do fechamento (histórico de ciclos)

Agregação líquida

Threshold mínimo e política

Reserva (sem dupla cobrança)

Bloqueios

Snapshot do destino

Nota fiscal antes do pagamento

Execução em lote (PIX)

Operações do payout

Erros comuns

Eventos de domínio

Próximos passos