Skip to main content
GET
Listar payouts de saques

Caso de uso

Use este endpoint para consultar payouts originados de lotes e reconciliar cada item com o comprovante TurbofyPay. Quando receipt.available for true, o item pode ter PDF em receipt.endpoint. Os dados de negocio da listagem seguem a mesma separacao do comprovante: destinatario declarado, beneficiario real, valores, tarifas e rastreio Pix.

Autenticacao

  • x-client-id
  • x-client-secret

Query params

  • limit: quantidade de itens por pagina. Padrao 25, maximo 100.
  • cursor: cursor retornado em pageInfo.nextCursor.
  • q: busca por beneficiario, documento, chave Pix, lote, referencia, endToEndId ou transferencia.
  • status: um ou mais status separados por virgula. Inclui REFUNDED para Pix concluido e posteriormente estornado. COMPLETED e CANCELED sao aceitos como aliases.
  • dateField: paidAt ou createdAt. Padrao paidAt.
  • dateFrom: data inicial em YYYY-MM-DD.
  • dateTo: data final em YYYY-MM-DD.
  • batchId: filtra por lote.
  • beneficiaryConfirmed: filtro operacional legado. A listagem padrao deve buscar beneficiario real para todos os itens.

Response de sucesso

Em 200, a API retorna:
  • items[]: itens de payout individuais.
  • declaredRecipient: nome e chave informados na solicitacao.
  • beneficiary: beneficiario real confirmado ou enriquecido, quando houver evidencia autoritativa.
  • fees: taxa variavel, taxa fixa alocada e total debitado.
  • tracking: endToEndId, transferencia, idempotencia, referencia e lote.
  • receipt: disponibilidade e endpoint do comprovante PDF.
  • statusReasonCode e statusReason: motivo de processamento, falha ou devolução. Veja Erros e estados do Pix Out.
  • refundedAt: momento do estorno, quando status for REFUNDED.
  • pageInfo: cursor para a proxima pagina.
Agencia, conta e ISPB nao sao retornados. Quando a instituicao financeira do beneficiario for confirmada pela conciliacao ou pelo comprovante oficial, ela aparece apenas em beneficiary.account.institution.

Exportar XLSX

Use GET /sellers/saques/payout-items/export.xlsx para baixar a planilha dos payouts filtrados. A exportacao aceita os mesmos filtros da listagem, exceto limit e cursor, e exporta todos os registros do filtro ativo, nao apenas a pagina atual.
Se os filtros retornarem mais de 10.000 registros, a API responde 422. Se algum item ainda nao tiver nome + documento completo + instituicao real do beneficiario apos as tentativas de conciliacao, a API tambem responde 422 com PAYOUT_BENEFICIARY_REQUIRED. Refine o filtro ou aguarde a conciliacao antes de exportar.

Beneficiario real e instituicao

Para payouts, declaredRecipient e somente o destinatario informado na solicitacao ou no arquivo de origem. Ele nunca substitui o beneficiario real. O beneficiario real deve vir de evidencia autoritativa da transacao Pix ou do comprovante oficial usado pela TurbofyPay para gerar o PDF com marca propria. A instituicao exibida precisa ser a instituicao financeira do recebedor real, por exemplo BCO C6 S.A. quando o recebedor recebeu no C6. Valores operacionais do provedor, PSP ou conta de infraestrutura, como nome da instituicao operacional da rota, nao devem aparecer como instituicao do beneficiario. A API tambem nao inventa instituicao a partir de ISPB.

Regras de negocio

  • A listagem retorna somente itens do merchant autenticado.
  • PAID e COMPLETED indicam payout pago para fins de comprovante.
  • SENT indica envio/processamento e ainda nao libera PDF.
  • REFUNDED indica que o Pix foi concluido, mas o valor foi devolvido posteriormente. Nao significa falha de envio; receipt.available fica false.
  • CANCELLED e CANCELED aparecem como cancelados.
  • O PDF e a planilha usam marca TurbofyPay e nao exibem nome de fornecedor operacional.
  • O PDF e sempre por item de payout. Nao existe comprovante financeiro unico do lote.
  • Documento e chave Pix completos aparecem apenas em contexto autenticado.
  • Agencia, conta, ISPB, payload bruto, provider e source nao fazem parte do contrato publico.

Payout estornado

Quando o banco ou provedor devolve um Pix ja concluido, o item muda para REFUNDED. A confirmacao em beneficiaryResolutionStatus continua indicando somente a identidade apurada do beneficiario; ela nao significa que o valor permaneceu liquidado.

Proximos passos

  1. Para baixar o PDF de um item pago, use receipt.endpoint quando receipt.available for true.
  2. Para criar novos pagamentos em lote, use Criar lote de payouts.

Authorizations

x-client-id
string
header
required

Client ID fornecido pela TurbofyPay.

x-client-secret
string
header
required

Client Secret fornecido pela TurbofyPay.

Headers

x-client-id
string
required

Identificador do integrador.

x-client-secret
string
required

Segredo de autenticacao do integrador.

Query Parameters

limit
integer
default:25

Quantidade de itens por pagina. Valor padrao: 25. Valor maximo: 100.

Required range: 1 <= x <= 100
cursor
string

Cursor retornado em pageInfo.nextCursor para buscar a proxima pagina.

q
string

Busca por beneficiario, documento, chave Pix, lote, referencia, endToEndId ou transferencia.

Maximum string length: 160
status
string

Um ou mais status separados por virgula. COMPLETED e CANCELED sao aceitos como aliases.

dateField
enum<string>
default:paidAt

Campo de data usado por dateFrom/dateTo.

Available options:
paidAt,
createdAt
dateFrom
string<date>

Data inicial no formato YYYY-MM-DD.

dateTo
string<date>

Data final no formato YYYY-MM-DD.

batchId
string

Filtra por identificador do lote.

Maximum string length: 120
beneficiaryConfirmed
boolean

Filtro operacional para itens com beneficiario real confirmado. A listagem padrao tenta retornar o beneficiario real de todos os itens.

Response

Itens de payout encontrados para o seller autenticado.

items
object[]
required
pageInfo
object
required
filters
object
Last modified on November 10, 2026