Consultar saldo do merchant
curl --request GET \
--url http://localhost:3030/v1/balance \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>'import requests
url = "http://localhost:3030/v1/balance"
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/v1/balance', 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/balance",
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/v1/balance"
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/v1/balance")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3030/v1/balance")
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{
"currency": "BRL",
"asOf": "2023-11-07T05:31:56Z",
"availableBalanceCents": 1,
"withdrawableCents": 1,
"pendingBalanceCents": 1,
"reservedBalanceCents": 1,
"medBlockedBalanceCents": 1,
"medRetainedBalanceCents": 1,
"medLostBalanceCents": 1,
"settlementDebtCents": 1,
"withdrawalFrozen": true,
"operationalHoldActive": true,
"nextReleaseAt": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}Saldo
Consultar saldo
Consulta segura do saldo saqueável, valores pendentes e reservas do próprio merchant.
GET
/
v1
/
balance
Consultar saldo do merchant
curl --request GET \
--url http://localhost:3030/v1/balance \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>'import requests
url = "http://localhost:3030/v1/balance"
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/v1/balance', 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/balance",
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/v1/balance"
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/v1/balance")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:3030/v1/balance")
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{
"currency": "BRL",
"asOf": "2023-11-07T05:31:56Z",
"availableBalanceCents": 1,
"withdrawableCents": 1,
"pendingBalanceCents": 1,
"reservedBalanceCents": 1,
"medBlockedBalanceCents": 1,
"medRetainedBalanceCents": 1,
"medLostBalanceCents": 1,
"settlementDebtCents": 1,
"withdrawalFrozen": true,
"operationalHoldActive": true,
"nextReleaseAt": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>"
},
"statusCode": 123,
"code": "<string>",
"message": "<string>"
}Autenticação
Enviex-client-id e x-client-secret pelo seu servidor. Todas as credenciais ativas podem consultar o próprio saldo, sem um novo escopo. Revogação, expiração e restrições de IP continuam aplicáveis. Nunca exponha o segredo no navegador ou aplicativo cliente.
A conta é identificada pela credencial. A requisição não aceita corpo nem parâmetros de consulta, incluindo merchantId. Essa consulta não exige assinatura HMAC nem chave de idempotência.
curl --request GET 'https://api.turbofypay.com/v1/balance' \
--header 'x-client-id: SEU_CLIENT_ID' \
--header 'x-client-secret: SEU_CLIENT_SECRET'
Valores retornados
Todos os valores monetários são inteiros em centavos da moedacurrency. asOf indica o instante da leitura, em ISO 8601.
| Campo | Significado |
|---|---|
availableBalanceCents | Saldo disponível para saque; igual a withdrawableCents. |
withdrawableCents | Valor saqueável após regras de liquidação, reservas e restrições. |
pendingBalanceCents | Valor pendente de liberação. |
reservedBalanceCents | Valor reservado pelo cálculo financeiro da plataforma. |
medBlockedBalanceCents | Bloqueio MED registrado/consolidado pelo serviço financeiro, considerando wallet e casos. Pode ser menor que a obrigação MED considerada no saldo saqueável; não representa toda retenção nem uma perda confirmada. |
medRetainedBalanceCents | Corresponde exatamente ao valor de retenção por MED exibido no painel no mesmo instante asOf da resposta, incluindo valores reservados em casos MED abertos. É 0 quando não há retenção por MED. |
medLostBalanceCents | Total acumulado, até asOf, dos débitos permanentes no saldo do merchant causados por MED. Representa perda efetivada, não valor apenas retido; é 0 quando não há débitos permanentes por MED. |
settlementDebtCents | Dívida de liquidação, separada do saldo saqueável. |
withdrawalFrozen | Indica restrição de saque. |
operationalHoldActive | Indica retenção operacional ativa. |
nextReleaseAt | Próxima liberação prevista em ISO 8601, ou null quando inexistente. |
medBlockedBalanceCents informa o bloqueio consolidado; medRetainedBalanceCents corresponde ao valor retido por MED exibido no painel no mesmo instante asOf; e medLostBalanceCents acumula débitos permanentes já realizados. Um caso MED aberto pode reduzir o saqueável antes de o bloqueio aparecer no valor registrado/consolidado. Consulte o histórico de devoluções no painel autenticado, na área MED — Contestações Pix.
Exemplo ilustrativo:
{
"currency": "BRL",
"asOf": "2026-11-04T12:00:00.000Z",
"availableBalanceCents": 10000,
"withdrawableCents": 10000,
"pendingBalanceCents": 2000,
"reservedBalanceCents": 0,
"medBlockedBalanceCents": 0,
"medRetainedBalanceCents": 0,
"medLostBalanceCents": 0,
"settlementDebtCents": 0,
"withdrawalFrozen": false,
"operationalHoldActive": false,
"nextReleaseAt": "2026-11-05T12:00:00.000Z"
}
Limites e erros
A resposta usaCache-Control: no-store. O limite é de 60 consultas por minuto por merchant por processo/instância da API, compartilhado pelas credenciais dessa conta nessa instância. O limite global por IP também se aplica; essa quota não é compartilhada entre processos ou réplicas.
| HTTP | Situação |
|---|---|
400 | Parâmetro ou corpo não permitido. |
401 | Credenciais ausentes, inválidas, expiradas ou revogadas. |
403 | Acesso recusado pela política de IP. |
429 | Limite de consultas excedido; respeite Retry-After quando informado. |
503 | Leitura financeira indisponível; não interpretar como saldo zero. |
Authorizations
Headers
Response
Default Response
Last modified on November 6, 2026