Listar payouts de saques
curl --request GET \
--url http://localhost:3030/sellers/saques/payout-items \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>'import requests
url = "http://localhost:3030/sellers/saques/payout-items"
headers = {
"x-client-id": "<api-key>",
"x-client-secret": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'x-client-id': '<api-key>', 'x-client-secret': '<api-key>'}
};
fetch('http://localhost:3030/sellers/saques/payout-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/sellers/saques/payout-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>"
],
]);
$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/sellers/saques/payout-items"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-client-id", "<api-key>")
req.Header.Add("x-client-secret", "<api-key>")
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/sellers/saques/payout-items")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3030/sellers/saques/payout-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>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"type": "payout_item",
"amountCents": 123,
"status": "PENDING",
"fees": {
"variableFeeCents": 123,
"allocatedBatchFeeCents": 123,
"feeCents": 123,
"totalDebitedCents": 123
},
"receipt": {
"available": true,
"endpoint": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"label": "<string>",
"batchId": "<string>",
"feeCents": 123,
"allocatedBatchFeeCents": 123,
"totalDebitedCents": 123,
"netAmountCents": 123,
"failureReason": "<string>",
"statusReasonCode": "<string>",
"statusReason": "<string>",
"declaredRecipient": {
"name": "<string>",
"pixKey": "<string>",
"pixKeyMasked": "<string>",
"pixKeyType": "<string>"
},
"beneficiary": {
"name": "<string>",
"document": "<string>",
"documentMasked": "<string>",
"documentType": "CPF",
"pixKey": "<string>",
"pixKeyMasked": "<string>",
"pixKeyType": "CPF",
"authoritative": true,
"capturedAt": "2023-11-07T05:31:56Z",
"account": {
"institution": "<string>"
}
},
"beneficiaryResolutionStatus": "<string>",
"tracking": {
"endToEndId": "<string>",
"transferId": "<string>",
"idempotencyKey": "<string>",
"batchId": "<string>",
"referenceId": "<string>"
},
"processedAt": "2023-11-07T05:31:56Z",
"settledAt": "2023-11-07T05:31:56Z",
"releasedAt": "2023-11-07T05:31:56Z",
"refundedAt": "2023-11-07T05:31:56Z"
}
],
"pageInfo": {
"limit": 50,
"nextCursor": "<string>",
"hasNextPage": true
},
"filters": {}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}Saques
Listar payouts de saques
Lista payouts do seller com filtros server-side, cursor, beneficiario real e exportacao XLSX.
GET
/
sellers
/
saques
/
payout-items
Listar payouts de saques
curl --request GET \
--url http://localhost:3030/sellers/saques/payout-items \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>'import requests
url = "http://localhost:3030/sellers/saques/payout-items"
headers = {
"x-client-id": "<api-key>",
"x-client-secret": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'x-client-id': '<api-key>', 'x-client-secret': '<api-key>'}
};
fetch('http://localhost:3030/sellers/saques/payout-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/sellers/saques/payout-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>"
],
]);
$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/sellers/saques/payout-items"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-client-id", "<api-key>")
req.Header.Add("x-client-secret", "<api-key>")
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/sellers/saques/payout-items")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3030/sellers/saques/payout-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>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"type": "payout_item",
"amountCents": 123,
"status": "PENDING",
"fees": {
"variableFeeCents": 123,
"allocatedBatchFeeCents": 123,
"feeCents": 123,
"totalDebitedCents": 123
},
"receipt": {
"available": true,
"endpoint": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"label": "<string>",
"batchId": "<string>",
"feeCents": 123,
"allocatedBatchFeeCents": 123,
"totalDebitedCents": 123,
"netAmountCents": 123,
"failureReason": "<string>",
"statusReasonCode": "<string>",
"statusReason": "<string>",
"declaredRecipient": {
"name": "<string>",
"pixKey": "<string>",
"pixKeyMasked": "<string>",
"pixKeyType": "<string>"
},
"beneficiary": {
"name": "<string>",
"document": "<string>",
"documentMasked": "<string>",
"documentType": "CPF",
"pixKey": "<string>",
"pixKeyMasked": "<string>",
"pixKeyType": "CPF",
"authoritative": true,
"capturedAt": "2023-11-07T05:31:56Z",
"account": {
"institution": "<string>"
}
},
"beneficiaryResolutionStatus": "<string>",
"tracking": {
"endToEndId": "<string>",
"transferId": "<string>",
"idempotencyKey": "<string>",
"batchId": "<string>",
"referenceId": "<string>"
},
"processedAt": "2023-11-07T05:31:56Z",
"settledAt": "2023-11-07T05:31:56Z",
"releasedAt": "2023-11-07T05:31:56Z",
"refundedAt": "2023-11-07T05:31:56Z"
}
],
"pageInfo": {
"limit": 50,
"nextCursor": "<string>",
"hasNextPage": true
},
"filters": {}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": {},
"traceId": "<string>"
}
}Caso de uso
Use este endpoint para consultar payouts originados de lotes e reconciliar cada item com o comprovante TurbofyPay. Quandoreceipt.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-idx-client-secret
Query params
limit: quantidade de itens por pagina. Padrao25, maximo100.cursor: cursor retornado empageInfo.nextCursor.q: busca por beneficiario, documento, chave Pix, lote, referencia,endToEndIdou transferencia.status: um ou mais status separados por virgula. IncluiREFUNDEDpara Pix concluido e posteriormente estornado.COMPLETEDeCANCELEDsao aceitos como aliases.dateField:paidAtoucreatedAt. PadraopaidAt.dateFrom: data inicial emYYYY-MM-DD.dateTo: data final emYYYY-MM-DD.batchId: filtra por lote.beneficiaryConfirmed: filtro operacional legado. A listagem padrao deve buscar beneficiario real para todos os itens.
Response de sucesso
Em200, 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.statusReasonCodeestatusReason: motivo de processamento, falha ou devolução. Veja Erros e estados do Pix Out.refundedAt: momento do estorno, quandostatusforREFUNDED.pageInfo: cursor para a proxima pagina.
beneficiary.account.institution.
{
"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
UseGET /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.
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: <client-id>" \
--header "x-client-secret: <client-secret>" \
--output payouts.xlsx
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.
PAIDeCOMPLETEDindicam payout pago para fins de comprovante.SENTindica envio/processamento e ainda nao libera PDF.REFUNDEDindica que o Pix foi concluido, mas o valor foi devolvido posteriormente. Nao significa falha de envio;receipt.availableficafalse.CANCELLEDeCANCELEDaparecem 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,
provideresourcenao fazem parte do contrato publico.
Payout estornado
Quando o banco ou provedor devolve um Pix ja concluido, o item muda paraREFUNDED. A confirmacao em beneficiaryResolutionStatus continua indicando
somente a identidade apurada do beneficiario; ela nao significa que o valor
permaneceu liquidado.
{
"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
- Para baixar o PDF de um item pago, use
receipt.endpointquandoreceipt.availablefortrue. - Para criar novos pagamentos em lote, use Criar lote de payouts.
Authorizations
Headers
Query Parameters
Last modified on November 10, 2026