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": {}
}
'

import requests

url = "http://localhost:3030/v1/payouts/batches"

payload = {
    "idempotencyKey": "<string>",
    "items": [
        {
            "pixKey": "<string>",
            "amountCents": 2,
            "recipientName": "<string>",
            "recipientDocument": "<string>",
            "referenceId": "<string>"
        }
    ],
    "description": "<string>",
    "metadata": {}
}
headers = {
    "x-client-id": "<api-key>",
    "x-client-secret": "<api-key>",
    "x-turbofy-timestamp": "<x-turbofy-timestamp>",
    "x-turbofy-signature": "<x-turbofy-signature>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-client-id': '<api-key>',
    'x-client-secret': '<api-key>',
    'x-turbofy-timestamp': '<x-turbofy-timestamp>',
    'x-turbofy-signature': '<x-turbofy-signature>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    idempotencyKey: '<string>',
    items: [
      {
        pixKey: '<string>',
        amountCents: 2,
        recipientName: '<string>',
        recipientDocument: '<string>',
        referenceId: '<string>'
      }
    ],
    description: '<string>',
    metadata: {}
  })
};

fetch('http://localhost:3030/v1/payouts/batches', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'idempotencyKey' => '<string>',
    'items' => [
        [
                'pixKey' => '<string>',
                'amountCents' => 2,
                'recipientName' => '<string>',
                'recipientDocument' => '<string>',
                'referenceId' => '<string>'
        ]
    ],
    'description' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:3030/v1/payouts/batches"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"<string>\",\n  \"items\": [\n    {\n      \"pixKey\": \"<string>\",\n      \"amountCents\": 2,\n      \"recipientName\": \"<string>\",\n      \"recipientDocument\": \"<string>\",\n      \"referenceId\": \"<string>\"\n    }\n  ],\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:3030/v1/payouts/batches")
  .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>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"<string>\",\n  \"items\": [\n    {\n      \"pixKey\": \"<string>\",\n      \"amountCents\": 2,\n      \"recipientName\": \"<string>\",\n      \"recipientDocument\": \"<string>\",\n      \"referenceId\": \"<string>\"\n    }\n  ],\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:3030/v1/payouts/batches")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.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>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"<string>\",\n  \"items\": [\n    {\n      \"pixKey\": \"<string>\",\n      \"amountCents\": 2,\n      \"recipientName\": \"<string>\",\n      \"recipientDocument\": \"<string>\",\n      \"referenceId\": \"<string>\"\n    }\n  ],\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "batchId": "<string>",
  "status": "<string>",
  "totalAmountCents": 123,
  "totalFeeCents": 123,
  "totalFundingCents": 123,
  "itemsCount": 123,
  "idempotencyReplay": true
}

{
  "batchId": "<string>",
  "status": "<string>",
  "totalAmountCents": 123,
  "totalFeeCents": 123,
  "totalFundingCents": 123,
  "itemsCount": 123,
  "idempotencyReplay": true
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "traceId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "traceId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "traceId": "<string>"
  }
}

POST

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": {}
}
'

import requests

url = "http://localhost:3030/v1/payouts/batches"

payload = {
    "idempotencyKey": "<string>",
    "items": [
        {
            "pixKey": "<string>",
            "amountCents": 2,
            "recipientName": "<string>",
            "recipientDocument": "<string>",
            "referenceId": "<string>"
        }
    ],
    "description": "<string>",
    "metadata": {}
}
headers = {
    "x-client-id": "<api-key>",
    "x-client-secret": "<api-key>",
    "x-turbofy-timestamp": "<x-turbofy-timestamp>",
    "x-turbofy-signature": "<x-turbofy-signature>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-client-id': '<api-key>',
    'x-client-secret': '<api-key>',
    'x-turbofy-timestamp': '<x-turbofy-timestamp>',
    'x-turbofy-signature': '<x-turbofy-signature>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    idempotencyKey: '<string>',
    items: [
      {
        pixKey: '<string>',
        amountCents: 2,
        recipientName: '<string>',
        recipientDocument: '<string>',
        referenceId: '<string>'
      }
    ],
    description: '<string>',
    metadata: {}
  })
};

fetch('http://localhost:3030/v1/payouts/batches', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'idempotencyKey' => '<string>',
    'items' => [
        [
                'pixKey' => '<string>',
                'amountCents' => 2,
                'recipientName' => '<string>',
                'recipientDocument' => '<string>',
                'referenceId' => '<string>'
        ]
    ],
    'description' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:3030/v1/payouts/batches"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"<string>\",\n  \"items\": [\n    {\n      \"pixKey\": \"<string>\",\n      \"amountCents\": 2,\n      \"recipientName\": \"<string>\",\n      \"recipientDocument\": \"<string>\",\n      \"referenceId\": \"<string>\"\n    }\n  ],\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	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>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:3030/v1/payouts/batches")
  .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>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"<string>\",\n  \"items\": [\n    {\n      \"pixKey\": \"<string>\",\n      \"amountCents\": 2,\n      \"recipientName\": \"<string>\",\n      \"recipientDocument\": \"<string>\",\n      \"referenceId\": \"<string>\"\n    }\n  ],\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:3030/v1/payouts/batches")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.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>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"idempotencyKey\": \"<string>\",\n  \"items\": [\n    {\n      \"pixKey\": \"<string>\",\n      \"amountCents\": 2,\n      \"recipientName\": \"<string>\",\n      \"recipientDocument\": \"<string>\",\n      \"referenceId\": \"<string>\"\n    }\n  ],\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "batchId": "<string>",
  "status": "<string>",
  "totalAmountCents": 123,
  "totalFeeCents": 123,
  "totalFundingCents": 123,
  "itemsCount": 123,
  "idempotencyReplay": true
}

{
  "batchId": "<string>",
  "status": "<string>",
  "totalAmountCents": 123,
  "totalFeeCents": 123,
  "totalFundingCents": 123,
  "itemsCount": 123,
  "idempotencyReplay": true
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "traceId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "traceId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "traceId": "<string>"
  }
}

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

HTTP	code	Quando ocorre
`401`	`INVALID_SIGNATURE`	Assinatura HMAC ausente, invalida ou expirada.
`401`	`INVALID_CREDENTIALS`	Credenciais ausentes ou invalidas.
`400`	`PAYOUTS_NOT_ENABLED`	Merchant sem payout habilitado.
`400`	`INSUFFICIENT_AVAILABLE_BALANCE`	Saldo insuficiente para financiar o lote.
`409`	`DUPLICATE_IDEMPOTENCY_KEY`	Chave repetida com payload diferente.
`409`	`WITHDRAWAL_FROZEN`	Saques/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

Consulte andamento em Consultar lote de payouts.
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

Show child attributes

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

Consultar cobranca PIX Consultar lote de payouts

Cobranca PIX

Payouts

Saques

Comprovantes

Criar lote de payouts

Caso de uso

Autenticacao

Pre-condicoes e requisitos

Request

Response de sucesso

Erros comuns reais

Regras de negocio e observacoes operacionais

Exemplo de codigo

Proximos passos

Authorizations

Headers

Body

Response

​Caso de uso

​Autenticacao

​Pre-condicoes e requisitos

​Request

​Response de sucesso

​Erros comuns reais

​Regras de negocio e observacoes operacionais

​Exemplo de codigo

​Proximos passos

Authorizations

Headers

Body

Response

Caso de uso

Autenticacao

Pre-condicoes e requisitos

Request

Response de sucesso

Erros comuns reais

Regras de negocio e observacoes operacionais

Exemplo de codigo

Proximos passos