Listar itens do lote de payouts
curl --request GET \
--url http://localhost:3030/v1/payouts/batches/{batchId}/items \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>' \
--header 'x-turbofy-signature: <x-turbofy-signature>' \
--header 'x-turbofy-timestamp: <x-turbofy-timestamp>'import requests
url = "http://localhost:3030/v1/payouts/batches/{batchId}/items"
headers = {
"x-client-id": "<api-key>",
"x-client-secret": "<api-key>",
"x-turbofy-timestamp": "<x-turbofy-timestamp>",
"x-turbofy-signature": "<x-turbofy-signature>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'x-client-id': '<api-key>',
'x-client-secret': '<api-key>',
'x-turbofy-timestamp': '<x-turbofy-timestamp>',
'x-turbofy-signature': '<x-turbofy-signature>'
}
};
fetch('http://localhost:3030/v1/payouts/batches/{batchId}/items', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "3030",
CURLOPT_URL => "http://localhost:3030/v1/payouts/batches/{batchId}/items",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-client-id: <api-key>",
"x-client-secret: <api-key>",
"x-turbofy-signature: <x-turbofy-signature>",
"x-turbofy-timestamp: <x-turbofy-timestamp>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://localhost:3030/v1/payouts/batches/{batchId}/items"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-client-id", "<api-key>")
req.Header.Add("x-client-secret", "<api-key>")
req.Header.Add("x-turbofy-timestamp", "<x-turbofy-timestamp>")
req.Header.Add("x-turbofy-signature", "<x-turbofy-signature>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://localhost:3030/v1/payouts/batches/{batchId}/items")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.header("x-turbofy-timestamp", "<x-turbofy-timestamp>")
.header("x-turbofy-signature", "<x-turbofy-signature>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3030/v1/payouts/batches/{batchId}/items")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-client-id"] = '<api-key>'
request["x-client-secret"] = '<api-key>'
request["x-turbofy-timestamp"] = '<x-turbofy-timestamp>'
request["x-turbofy-signature"] = '<x-turbofy-signature>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"status": "PENDING",
"amountCents": 123,
"feeCents": 123,
"netAmountCents": 123,
"recipientName": "<string>",
"pixKeyType": "<string>",
"referenceId": "<string>",
"lastError": "<string>",
"lastErrorCode": "<string>",
"statusReasonCode": "<string>",
"statusReason": "<string>",
"settledAt": "2023-11-07T05:31:56Z",
"releasedAt": "2023-11-07T05:31:56Z",
"refundedAt": "2023-11-07T05:31:56Z",
"rowIndex": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"limit": 123,
"offset": 123
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}Payouts
Listar itens de payout
Lista os itens de um lote de payouts com beneficiario real, status, rastreio e dados estruturados do comprovante TurbofyPay.
GET
/
v1
/
payouts
/
batches
/
{batchId}
/
items
Listar itens do lote de payouts
curl --request GET \
--url http://localhost:3030/v1/payouts/batches/{batchId}/items \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>' \
--header 'x-turbofy-signature: <x-turbofy-signature>' \
--header 'x-turbofy-timestamp: <x-turbofy-timestamp>'import requests
url = "http://localhost:3030/v1/payouts/batches/{batchId}/items"
headers = {
"x-client-id": "<api-key>",
"x-client-secret": "<api-key>",
"x-turbofy-timestamp": "<x-turbofy-timestamp>",
"x-turbofy-signature": "<x-turbofy-signature>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'x-client-id': '<api-key>',
'x-client-secret': '<api-key>',
'x-turbofy-timestamp': '<x-turbofy-timestamp>',
'x-turbofy-signature': '<x-turbofy-signature>'
}
};
fetch('http://localhost:3030/v1/payouts/batches/{batchId}/items', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "3030",
CURLOPT_URL => "http://localhost:3030/v1/payouts/batches/{batchId}/items",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-client-id: <api-key>",
"x-client-secret: <api-key>",
"x-turbofy-signature: <x-turbofy-signature>",
"x-turbofy-timestamp: <x-turbofy-timestamp>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://localhost:3030/v1/payouts/batches/{batchId}/items"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-client-id", "<api-key>")
req.Header.Add("x-client-secret", "<api-key>")
req.Header.Add("x-turbofy-timestamp", "<x-turbofy-timestamp>")
req.Header.Add("x-turbofy-signature", "<x-turbofy-signature>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://localhost:3030/v1/payouts/batches/{batchId}/items")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.header("x-turbofy-timestamp", "<x-turbofy-timestamp>")
.header("x-turbofy-signature", "<x-turbofy-signature>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3030/v1/payouts/batches/{batchId}/items")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-client-id"] = '<api-key>'
request["x-client-secret"] = '<api-key>'
request["x-turbofy-timestamp"] = '<x-turbofy-timestamp>'
request["x-turbofy-signature"] = '<x-turbofy-signature>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"status": "PENDING",
"amountCents": 123,
"feeCents": 123,
"netAmountCents": 123,
"recipientName": "<string>",
"pixKeyType": "<string>",
"referenceId": "<string>",
"lastError": "<string>",
"lastErrorCode": "<string>",
"statusReasonCode": "<string>",
"statusReason": "<string>",
"settledAt": "2023-11-07T05:31:56Z",
"releasedAt": "2023-11-07T05:31:56Z",
"refundedAt": "2023-11-07T05:31:56Z",
"rowIndex": 123,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"limit": 123,
"offset": 123
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}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-idx-client-secretx-turbofy-timestampx-turbofy-signature
Pre-condicoes e requisitos
batchIddeve 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.
limit: quantidade maxima de itens, entre1e100. Padrao:20.offset: deslocamento inicial da lista. Padrao:0.
Response de sucesso
Em200, 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 ereferenceId.receipt: disponibilidade do PDF e dados estruturados equivalentes ao comprovante.lastErrorCode,lastError,statusReasonCodeestatusReason: 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
Quandoreceipt.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.
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
{
"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.endpointsomente quandoreceipt.availablefortrue. receipt.detailsficanullquando ainda nao existe comprovante do item.- O comprovante e os dados estruturados usam a marca TurbofyPay e nao exibem nome de fornecedor operacional.
beneficiarysepara o beneficiario real dodeclaredRecipient, que e o destinatario declarado na criacao.- A API nao inventa instituicao a partir de ISPB e nao usa
declaredRecipientcomo beneficiario real. - Use
tracking.endToEndIdeauthenticationCodepara conciliacao com o comprovante. REFUNDEDe um estado terminal proprio. Ele informa que houve liquidacao seguida de estorno; nao deve ser tratado comoFAILED.beneficiaryResolutionStatus: CONFIRMEDconfirma a identidade apurada, nao a permanencia da liquidacao.
Evento de estorno
Integracoes inscritas recebempayout.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
- Consulte o resumo do lote em Consultar lote de payouts.
- Baixe o PDF do item em Baixar comprovante de payout quando
receipt.availablefortrue.
Authorizations
Headers
Last modified on November 10, 2026