Skip to main content
GET
/
v1
/
payouts
/
batches
/
{batchId}
Consultar lote de payouts
curl --request GET \
  --url http://localhost:3030/v1/payouts/batches/{batchId} \
  --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>'
{
  "id": "<string>",
  "status": "<string>",
  "totalAmountCents": 123,
  "totalFeeCents": 123,
  "totalItems": 123,
  "paidItems": 123,
  "failedItems": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "items": [
    {
      "id": "<string>",
      "status": "<string>",
      "amountCents": 123,
      "feeCents": 123,
      "netAmountCents": 123,
      "recipientName": "<string>",
      "pixKeyType": "<string>",
      "referenceId": "<string>",
      "lastError": "<string>",
      "lastErrorCode": "<string>",
      "settledAt": "2023-11-07T05:31:56Z",
      "releasedAt": "2023-11-07T05:31:56Z",
      "rowIndex": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "totalNetCents": 123
}

​
Caso de uso

Use esta rota para acompanhar o estado de um lote de payouts e atualizar conciliacao financeira no seu sistema.

​
Autenticacao

  • x-client-id
  • x-client-secret
  • x-turbofy-timestamp
  • x-turbofy-signature

​
Pre-condicoes e requisitos

  • batchId deve pertencer ao merchant autenticado.
  • Assinatura HMAC valida dentro da janela de tempo.

​
Request

Parametro principal:
  • batchId (path): identificador do lote.

​
Response de sucesso

Em 200, a API retorna:
  • id e status
  • totalAmountCents, totalFeeCents, totalNetCents
  • totalItems, paidItems, failedItems
  • items[] com status de cada transferencia
  • createdAt e updatedAt

​
Erros comuns reais

HTTPcodeQuando ocorre
401INVALID_SIGNATUREAssinatura ausente, invalida ou expirada.
401INVALID_CREDENTIALSCredenciais ausentes ou invalidas.
404BATCH_NOT_FOUNDLote inexistente para o merchant autenticado.

​
Regras de negocio e observacoes operacionais

  • A consulta retorna somente lotes do merchant autenticado.
  • Para detalhamento por item, use GET /v1/payouts/batches/{batchId}/items.
  • Se o lote iniciou processamento, contadores de itens refletem progresso real.

​
Exemplo de codigo

curl --request GET \
  --url https://api.turbofypay.com/v1/payouts/batches/4e5038b0-5f73-4e67-a6ad-54ab4106ac78 \
  --header "x-client-id: <client-id>" \
  --header "x-client-secret: <client-secret>" \
  --header "x-turbofy-timestamp: 1772805000000" \
  --header "x-turbofy-signature: <hmac-sha256>"

​
Proximos passos

  1. Para nova criacao, use Criar lote de payouts.
  2. Para itens individuais, use GET /v1/payouts/batches/{batchId}/items na secao de rotas publicas.

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

Lote encontrado.

​
id
string
required
​
status
string
required
​
totalAmountCents
integer
required
​
totalFeeCents
integer
required
​
totalItems
integer
required
​
paidItems
integer
required
​
failedItems
integer
required
​
createdAt
string<date-time>
required
​
updatedAt
string<date-time>
required
​
items
object[]
required
​
totalNetCents
integer
Last modified on April 13, 2026