Skip to main content
GET
Listar itens do lote de payouts

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.
  • 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

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

Proximos passos

  1. Consulte o resumo do lote em Consultar lote de payouts.
  2. Baixe o PDF do item em Baixar comprovante de payout quando receipt.available for true.

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.

x-turbofy-timestamp
string
required

Timestamp utilizado na assinatura HMAC.

x-turbofy-signature
string
required

Assinatura HMAC SHA-256 da requisicao.

Path Parameters

batchId
string
required

Response

Itens do lote retornados com sucesso.

items
object[]
required
limit
integer
required
offset
integer
required
Last modified on November 10, 2026