> ## 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 itens de payout

> Lista os itens de um lote de payouts com beneficiario real, status, rastreio e dados estruturados do comprovante TurbofyPay.

## Caso de uso

Use esta rota para consultar cada transferencia de um lote de payouts e reconciliar o item com seu sistema interno.

Quando o item possui comprovante disponivel, `receipt.details` retorna os mesmos dados de negocio usados no PDF com marca TurbofyPay: dados da transacao, pagador, beneficiario real, instituicao do beneficiario, autenticacao e metodo de iniciacao.

## Autenticacao

Headers obrigatorios:

* `x-client-id`
* `x-client-secret`
* `x-turbofy-timestamp`
* `x-turbofy-signature`

## Pre-condicoes e requisitos

* `batchId` deve pertencer ao merchant autenticado.
* A API key precisa ter permissao `payout:read`.
* Assinatura HMAC valida dentro da janela de tempo.

## Request

Parametro principal:

* `batchId` (path): identificador do lote.

Parametros opcionais de paginacao:

* `limit`: quantidade maxima de itens, entre `1` e `100`. Padrao: `20`.
* `offset`: deslocamento inicial da lista. Padrao: `0`.

## Response de sucesso

Em `200`, a API retorna:

* `items[]`: itens individuais do lote.
* `declaredRecipient`: destinatario informado na criacao do payout.
* `beneficiary`: beneficiario real confirmado ou enriquecido, em formato compacto para listagem.
* `beneficiaryResolutionStatus`: estado da resolucao do beneficiario.
* `fees`: tarifa variavel, tarifa fixa alocada e total debitado do item.
* `tracking`: `endToEndId`, chave de idempotencia e `referenceId`.
* `receipt`: disponibilidade do PDF e dados estruturados equivalentes ao comprovante.
* `lastErrorCode`, `lastError`, `statusReasonCode` e `statusReason`: códigos e mensagens públicas 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`: data da devolução quando o Pix foi concluído e posteriormente devolvido.

### Dados do comprovante

Quando `receipt.available === true`, `receipt.details` inclui:

* `transaction`: valor, data, status efetivado, autenticacao, descricao e metodo de iniciacao.
* `payer`: merchant pagador, documento e instituicao TurbofyPay.
* `recipient`: beneficiario real que recebeu o payout, documento mascarado e instituicao financeira.
* `authenticationCode`: codigo de autenticacao usado no comprovante.

Agencia, conta e ISPB nao sao retornados neste endpoint nem no comprovante de payout. Quando a instituicao financeira do beneficiario real for confirmada pela conciliacao ou pelo comprovante oficial, ela aparece em `beneficiary.institution` e em `receipt.details.recipient.institution`.

## Beneficiario real

`declaredRecipient` e o destinatario declarado pelo integrador na criacao do
payout. Ele ajuda na conciliacao operacional, mas nao prova quem recebeu o Pix.

`beneficiary` e o beneficiario real confirmado pela TurbofyPay a partir da
transacao Pix, do rastreio do provedor e do comprovante oficial usado como
evidencia. A instituicao em `beneficiary.institution` deve ser o banco ou a
instituicao financeira do recebedor real. Nomes de PSP, fornecedor, rota
operacional ou conta de infraestrutura nao devem ser tratados como instituicao
do beneficiario.

## Exemplo de response

```json theme={null}
{
  "items": [
    {
      "id": "b892f167-1b3b-4718-a0b4-5ef81fc4d14b",
      "rowIndex": 1,
      "status": "PAID",
      "amountCents": 1000,
      "feeCents": 100,
      "allocatedBatchFeeCents": 100,
      "totalDebitedCents": 1200,
      "netAmountCents": 900,
      "recipientName": "Recebedor",
      "pixKeyType": "CPF",
      "referenceId": "ref-1",
      "declaredRecipient": {
        "name": "Recebedor",
        "pixKey": "48297507823",
        "pixKeyMasked": "48***23",
        "pixKeyType": "CPF"
      },
      "beneficiary": {
        "name": "GEOVANNA DE OLIVEIRA MOURA",
        "document": "48297507823",
        "documentMasked": "482.***.***-23",
        "documentType": "CPF",
        "institution": "BCO C6 S.A.",
        "pixKey": "48297507823",
        "pixKeyMasked": "48***23",
        "pixKeyType": "CPF",
        "authoritative": true,
        "capturedAt": "2026-06-11T19:34:00.000Z"
      },
      "beneficiaryResolutionStatus": "CONFIRMED",
      "fees": {
        "variableFeeCents": 100,
        "allocatedBatchFeeCents": 100,
        "feeCents": 200,
        "totalDebitedCents": 1200
      },
      "receipt": {
        "available": true,
        "endpoint": "/v1/payouts/batches/batch-1/items/b892f167-1b3b-4718-a0b4-5ef81fc4d14b/receipt",
        "details": {
          "title": "Comprovante de transferência via Pix",
          "transaction": {
            "amountCents": 1000,
            "amountFormatted": "R$ 10,00",
            "paidAt": "2026-06-11T19:34:00.000Z",
            "paidAtFormatted": "11 de jun. de 2026, 16:34",
            "status": "Efetivado",
            "authentication": "E35713491202606111933469418b70c1",
            "description": "Bulk payout ref:ref-1",
            "initiationMethod": "Chave Pix"
          },
          "payer": {
            "name": "jonadab.leite",
            "document": "482.975.078-23",
            "documentMasked": null,
            "documentType": "CPF",
            "institution": "TurbofyPay"
          },
          "recipient": {
            "name": "GEOVANNA DE OLIVEIRA MOURA",
            "document": null,
            "documentMasked": "***.975.078-**",
            "documentType": "CPF",
            "institution": "BCO C6 S.A."
          },
          "authenticationCode": "E35713491202606111933469418b70c1"
        }
      },
      "tracking": {
        "endToEndId": "E35713491202606111933469418b70c1",
        "idempotencyKey": "idem-item-1",
        "referenceId": "ref-1"
      },
      "lastError": null,
      "lastErrorCode": null,
      "settledAt": "2026-06-11T19:34:00.000Z",
      "releasedAt": null,
      "createdAt": "2026-06-11T19:33:00.000Z",
      "updatedAt": "2026-06-11T19:34:00.000Z"
    }
  ],
  "limit": 20,
  "offset": 0
}
```

## Regras de negocio e observacoes operacionais

* O PDF deve ser baixado em `receipt.endpoint` somente quando `receipt.available` for `true`.
* `receipt.details` fica `null` quando ainda nao existe comprovante do item.
* O comprovante e os dados estruturados usam a marca TurbofyPay e nao exibem nome de fornecedor operacional.
* `beneficiary` separa o beneficiario real do `declaredRecipient`, que e o destinatario declarado na criacao.
* A API nao inventa instituicao a partir de ISPB e nao usa `declaredRecipient` como beneficiario real.
* Use `tracking.endToEndId` e `authenticationCode` para conciliacao com o comprovante.
* `REFUNDED` e um estado terminal proprio. Ele informa que houve liquidacao seguida de estorno; nao deve ser tratado como `FAILED`.
* `beneficiaryResolutionStatus: CONFIRMED` confirma a identidade apurada, nao a permanencia da liquidacao.

### Evento de estorno

Integracoes inscritas recebem `payout.item.refunded` com `itemId`, `batchId`,
`status: REFUNDED`, `refundedAt`, `reasonCode`, valor e identificadores de
conciliacao. O `eventId` e deterministico para permitir deduplicacao em replays.

## Erros comuns reais

| HTTP | code | Quando ocorre |
| - | - | - |
| `401` | `INVALID_SIGNATURE` | Assinatura ausente, invalida ou expirada. |
| `401` | `INVALID_CREDENTIALS` | Credenciais ausentes ou invalidas. |
| `404` | `BATCH_NOT_FOUND` | Lote inexistente para o merchant autenticado. |

## Proximos passos

1. Consulte o resumo do lote em [Consultar lote de payouts](https://docs.turbofypay.com/pages/reference/payouts/consultar-lote-payouts.md).
2. Baixe o PDF do item em [Baixar comprovante de payout](https://docs.turbofypay.com/pages/reference/comprovantes/baixar-comprovante-payout-item.md) quando `receipt.available` for `true`.


## OpenAPI

````yaml GET /v1/payouts/batches/{batchId}/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:
  /v1/payouts/batches/{batchId}/items:
    get:
      tags:
        - Payouts
      summary: Listar itens do lote de payouts
      description: Lista os itens de um lote de payouts.
      operationId: listPayoutBatchItems
      parameters:
        - schema:
            type: string
          in: path
          name: batchId
          required: true
        - $ref: '#/components/parameters/XClientId'
        - $ref: '#/components/parameters/XClientSecret'
        - $ref: '#/components/parameters/XTurbofyTimestamp'
        - $ref: '#/components/parameters/XTurbofySignature'
      responses:
        '200':
          description: Itens do lote retornados com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutBatchItemsListResponse'
        '401':
          description: Credenciais ou assinatura invalidas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Lote nao encontrado para o merchant autenticado.
          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.
    XTurbofyTimestamp:
      name: x-turbofy-timestamp
      in: header
      required: true
      schema:
        type: string
      description: Timestamp utilizado na assinatura HMAC.
    XTurbofySignature:
      name: x-turbofy-signature
      in: header
      required: true
      schema:
        type: string
      description: Assinatura HMAC SHA-256 da requisicao.
  schemas:
    PayoutBatchItemsListResponse:
      type: object
      required:
        - items
        - limit
        - offset
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PayoutBatchItemResponse'
        limit:
          type: integer
        offset:
          type: integer
    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
    PayoutBatchItemResponse:
      type: object
      required:
        - id
        - status
        - amountCents
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - SENT
            - PAID
            - REFUNDED
            - FAILED
            - CANCELLED
        amountCents:
          type: integer
        feeCents:
          type: integer
        netAmountCents:
          type: integer
        recipientName:
          type: string
        pixKeyType:
          type: string
        referenceId:
          type: string
          nullable: true
        lastError:
          type: string
          nullable: true
        lastErrorCode:
          type: string
          nullable: true
        statusReasonCode:
          type: string
          nullable: true
        statusReason:
          type: string
          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
        rowIndex:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  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.