Skip to main content
POST
/
v1
/
payouts
/
batches
Criar lote de payouts
curl --request POST \
  --url http://localhost:3030/v1/payouts/batches \
  --header 'Content-Type: application/json' \
  --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>' \
  --data '
{
  "idempotencyKey": "<string>",
  "items": [
    {
      "pixKey": "<string>",
      "amountCents": 2,
      "recipientName": "<string>",
      "recipientDocument": "<string>",
      "referenceId": "<string>"
    }
  ],
  "description": "<string>",
  "metadata": {}
}
'
{
  "batchId": "<string>",
  "status": "<string>",
  "totalAmountCents": 123,
  "totalFeeCents": 123,
  "totalFundingCents": 123,
  "itemsCount": 123,
  "idempotencyReplay": true
}

​
Caso de uso

Use este endpoint para enviar pagamentos em lote para multiplos recebedores com reserva de saldo e processamento assincrono.

​
Autenticacao

Headers obrigatorios:
  • x-client-id
  • x-client-secret
  • x-turbofy-timestamp
  • x-turbofy-signature

​
Pre-condicoes e requisitos

  • Merchant precisa ter payouts habilitado.
  • idempotencyKey entre 8 e 100 caracteres.
  • Cada item precisa de pixKey, pixKeyType, amountCents e recipientName.
  • A assinatura HMAC deve ser recalculada em toda requisicao.

​
Request

Campos principais:
  • idempotencyKey: deduplicacao da operacao.
  • description: descricao operacional.
  • metadata: dados auxiliares de conciliacao.
  • items[]: transferencias individuais do lote.

​
Response de sucesso

  • 201: lote criado.
  • 200: replay idempotente com mesmo payload.
Campos de retorno principais:
  • batchId
  • status
  • totalAmountCents
  • totalFeeCents
  • totalFundingCents
  • itemsCount
  • idempotencyReplay
Fluxo visual de criacao de lote de payouts com assinatura HMAC, idempotencia, reserva de saldo, processamento assincrono e auditoria. O lote nasce com reserva financeira e trilha de auditoria. Use a chave de idempotencia para evitar duplicidade e acompanhe o processamento depois da criacao.

​
Erros comuns reais

201 CREATED400 PAYOUTS_NOT_ENABLED409 DUPLICATE_IDEMPOTENCY_KEY
HTTPcodeQuando ocorre
401INVALID_SIGNATUREAssinatura HMAC ausente, invalida ou expirada.
401INVALID_CREDENTIALSCredenciais ausentes ou invalidas.
400PAYOUTS_NOT_ENABLEDMerchant sem payout habilitado.
400INSUFFICIENT_AVAILABLE_BALANCESaldo insuficiente para financiar o lote.
409DUPLICATE_IDEMPOTENCY_KEYChave repetida com payload diferente.
409WITHDRAWAL_FROZENSaques/payouts bloqueados temporariamente.

​
Regras de negocio e observacoes operacionais

  • A idempotencia e aplicada por merchant.
  • O saldo e reservado no momento da criacao.
  • Processamento dos itens acontece apos criacao do lote.
  • Para auditoria, registre batchId, idempotencyKey e traceId.

​
Exemplo de codigo

curl --request POST \
  --url https://api.turbofypay.com/v1/payouts/batches \
  --header "x-client-id: <client-id>" \
  --header "x-client-secret: <client-secret>" \
  --header "x-turbofy-timestamp: 1772805000000" \
  --header "x-turbofy-signature: <hmac-sha256>" \
  --header "Content-Type: application/json" \
  --data '{
    "idempotencyKey": "folha-empresa-2026-03-06",
    "description": "Folha semanal",
    "items": [
      {
        "pixKey": "recebedor@example.test",
        "pixKeyType": "EMAIL",
        "amountCents": 250000,
        "recipientName": "Recebedor Exemplo",
        "recipientDocument": "00000000000",
        "referenceId": "payout-001"
      }
    ]
  }'

​
Proximos passos

  1. Consulte andamento em Consultar lote de payouts.
  2. Para troubleshooting de assinatura, revise Autenticacao.

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.

Body

application/json
​
idempotencyKey
string
required
Required string length: 8 - 100
​
items
object[]
required
Minimum array length: 1
​
description
string
Maximum string length: 255
​
metadata
object

Response

Replay de idempotencia para o mesmo payload.

​
batchId
string
required
​
status
string
required
​
totalAmountCents
integer
required
​
totalFeeCents
integer
required
​
totalFundingCents
integer
required
​
itemsCount
integer
required
​
idempotencyReplay
boolean
required
Last modified on June 1, 2026