> ## Documentation Index > Fetch the complete documentation index at: https://docs.turbofypay.com/llms.txt > Use this file to discover all available pages before exploring further. # Listar payouts de saques > Lista payouts do seller com filtros server-side, cursor, beneficiario real e exportacao XLSX. ## 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](https://docs.turbofypay.com/pages/reference/payouts/erros-pix-out.md). * `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`. ```json theme={null} { "items": [ { "id": "b892f167-1b3b-4718-a0b4-5ef81fc4d14b", "type": "payout_item", "label": "Payout", "batchId": "batch-1", "amountCents": 1000, "feeCents": 100, "allocatedBatchFeeCents": 100, "totalDebitedCents": 1200, "status": "PAID", "declaredRecipient": { "name": "Recebedor declarado", "pixKey": "48297507823", "pixKeyMasked": "482.***.***-23", "pixKeyType": "CPF" }, "beneficiary": { "name": "GEOVANNA DE OLIVEIRA MOURA", "document": "48297507823", "documentMasked": "482.***.***-23", "documentType": "CPF", "pixKey": "48297507823", "pixKeyMasked": "482.***.***-23", "pixKeyType": "CPF", "authoritative": true, "account": { "institution": "BCO C6 S.A." } }, "beneficiaryResolutionStatus": "CONFIRMED", "fees": { "variableFeeCents": 100, "allocatedBatchFeeCents": 100, "feeCents": 200, "totalDebitedCents": 1200 }, "receipt": { "available": true, "endpoint": "/sellers/saques/payout-items/b892f167-1b3b-4718-a0b4-5ef81fc4d14b/receipt" }, "tracking": { "endToEndId": "E35713491202606111933469418b70c1", "transferId": "550e8400-e29b-41d4-a716-446655440000", "referenceId": "ref-1", "batchId": "batch-1" }, "createdAt": "2026-06-11T19:33:00.000Z", "settledAt": "2026-06-11T19:34:00.000Z" } ], "pageInfo": { "limit": 25, "nextCursor": null, "hasNextPage": false } } ``` ## 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. ```bash theme={null} curl --request GET \ --url "https://api.turbofypay.com/sellers/saques/payout-items/export.xlsx?status=PAID&dateField=paidAt&dateFrom=2026-06-01&dateTo=2026-06-30" \ --header "x-client-id: " \ --header "x-client-secret: " \ --output payouts.xlsx ``` 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. ```json theme={null} { "id": "b892f167-1b3b-4718-a0b4-5ef81fc4d14b", "status": "REFUNDED", "settledAt": "2026-06-22T12:23:38.000Z", "refundedAt": "2026-06-22T12:24:20.770Z", "statusReasonCode": "PROVIDER_REFUNDED", "statusReason": "Pix concluído e posteriormente devolvido pelo banco/provedor.", "beneficiaryResolutionStatus": "CONFIRMED", "receipt": { "available": false, "endpoint": null } } ``` ## 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](https://docs.turbofypay.com/pages/reference/payouts/criar-lote-payouts.md). ## OpenAPI ````yaml GET /sellers/saques/payout-items openapi: 3.0.3 info: title: Turbofy Public API version: 2.0.0 description: >- Especificacao publica da API TurbofyPay para Cobranca PIX, Saldo, Saques, Webhooks e Payouts. contact: name: Turbofy Team email: suporte@turbofy.com url: https://turbofy.com license: name: Proprietary url: https://turbofy.com/terms servers: - url: http://localhost:3030 description: Development Server - url: https://api.turbofypay.com description: Production Server security: [] tags: - name: Cobranca PIX description: Operacoes de cobranca PIX para integradores. - name: Saques description: Operacoes de saque para sellers. - name: Webhooks description: Cadastro e consulta de webhooks. - name: Payouts description: Gestao de lotes de payout. - name: Saldo description: Consulta do proprio saldo com credenciais de integracao. externalDocs: description: Documentação completa url: https://docs.turbofy.com paths: /sellers/saques/payout-items: get: tags: - Saques summary: Listar payouts de saques description: >- Lista itens de payout do seller autenticado com paginacao por cursor, filtros server-side e beneficiario real quando confirmado. operationId: listSellerPayoutItems parameters: - $ref: '#/components/parameters/XClientId' - $ref: '#/components/parameters/XClientSecret' - name: limit in: query required: false description: 'Quantidade de itens por pagina. Valor padrao: 25. Valor maximo: 100.' schema: type: integer minimum: 1 maximum: 100 default: 25 - name: cursor in: query required: false description: >- Cursor retornado em pageInfo.nextCursor para buscar a proxima pagina. schema: type: string - name: q in: query required: false description: >- Busca por beneficiario, documento, chave Pix, lote, referencia, endToEndId ou transferencia. schema: type: string maxLength: 160 - name: status in: query required: false description: >- Um ou mais status separados por virgula. COMPLETED e CANCELED sao aceitos como aliases. schema: type: string - name: dateField in: query required: false description: Campo de data usado por dateFrom/dateTo. schema: type: string enum: - paidAt - createdAt default: paidAt - name: dateFrom in: query required: false description: Data inicial no formato YYYY-MM-DD. schema: type: string format: date - name: dateTo in: query required: false description: Data final no formato YYYY-MM-DD. schema: type: string format: date - name: batchId in: query required: false description: Filtra por identificador do lote. schema: type: string maxLength: 120 - name: beneficiaryConfirmed in: query required: false description: >- Filtro operacional para itens com beneficiario real confirmado. A listagem padrao tenta retornar o beneficiario real de todos os itens. schema: type: boolean responses: '200': description: Itens de payout encontrados para o seller autenticado. content: application/json: schema: $ref: '#/components/schemas/SellerPayoutItemListResponse' '401': description: Credenciais ausentes ou invalidas. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - clientCredentials: [] clientSecret: [] components: parameters: XClientId: name: x-client-id in: header required: true schema: type: string description: Identificador do integrador. XClientSecret: name: x-client-secret in: header required: true schema: type: string description: Segredo de autenticacao do integrador. schemas: SellerPayoutItemListResponse: type: object required: - items - pageInfo properties: items: type: array items: $ref: '#/components/schemas/SellerPayoutItemObject' pageInfo: type: object required: - limit - nextCursor - hasNextPage properties: limit: type: integer minimum: 1 maximum: 100 nextCursor: type: string nullable: true hasNextPage: type: boolean filters: type: object additionalProperties: true ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true traceId: type: string SellerPayoutItemObject: type: object required: - id - type - status - amountCents - fees - receipt - createdAt properties: id: type: string type: type: string enum: - payout_item label: type: string batchId: type: string amountCents: type: integer feeCents: type: integer allocatedBatchFeeCents: type: integer totalDebitedCents: type: integer netAmountCents: type: integer status: type: string enum: - PENDING - PROCESSING - SENT - PAID - REFUNDED - FAILED - CANCELLED failureReason: type: string nullable: true statusReasonCode: type: string nullable: true statusReason: type: string nullable: true declaredRecipient: type: object properties: name: type: string nullable: true pixKey: type: string nullable: true pixKeyMasked: type: string nullable: true pixKeyType: type: string nullable: true beneficiary: $ref: '#/components/schemas/SellerPayoutItemBeneficiary' beneficiaryResolutionStatus: type: string fees: type: object properties: variableFeeCents: type: integer allocatedBatchFeeCents: type: integer feeCents: type: integer totalDebitedCents: type: integer receipt: type: object properties: available: type: boolean endpoint: type: string nullable: true tracking: type: object properties: endToEndId: type: string nullable: true transferId: type: string nullable: true idempotencyKey: type: string nullable: true batchId: type: string nullable: true referenceId: type: string nullable: true createdAt: type: string format: date-time processedAt: type: string format: date-time nullable: true settledAt: type: string format: date-time nullable: true releasedAt: type: string format: date-time nullable: true refundedAt: type: string format: date-time nullable: true SellerPayoutItemBeneficiary: type: object nullable: true properties: name: type: string nullable: true document: type: string nullable: true documentMasked: type: string nullable: true documentType: type: string enum: - CPF - CNPJ nullable: true pixKey: type: string nullable: true pixKeyMasked: type: string nullable: true pixKeyType: type: string enum: - CPF - CNPJ - EMAIL - PHONE - EVP nullable: true authoritative: type: boolean capturedAt: type: string format: date-time nullable: true account: type: object properties: institution: type: string nullable: true securitySchemes: clientCredentials: type: apiKey in: header name: x-client-id description: Client ID fornecido pela TurbofyPay. clientSecret: type: apiKey in: header name: x-client-secret description: Client Secret fornecido pela TurbofyPay. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.