Consultando saldo
Consultando o Saldo
A consulta de saldo na API do Pagou permite obter o saldo disponível do cliente associado à chave de API utilizada.
Visão Geral Técnica
O endpoint GET
/v1/customers/balance
retorna o saldo disponível do cliente em reais, identificado pela chave de API fornecida no cabeçalho X-API-KEY
. A operação é síncrona, retornando 200 OK
com um corpo JSON contendo o campo balance.
Especificações:
Método: GET
URL:
Produção:
https://api.pagou.com.br/v1/customers/balance
Sandbox:
https://sandbox.api.pagou.com.br/v1/customers/balance
Autenticação: Cabeçalho
X-API-KEY
com chave do painel.Content-Type:
application/json
Resposta: Status
200 OK
com corpo JSON contendo o saldo do cliente.Erros:
400 Bad Request
,401 Unauthorized
,404 Not Found
,500 Internal Server Error
.
Cabeçalhos
Cabeçalho
Valor
Descrição
X-API-KEY
sua_chave_api
Chave de autenticação.
Content-Type
application/json
Formato JSON para a requisição.
User-Agent
NomeDaSuaAplicacao/1.0
Identificador da aplicação (ex.: MinhaLoja/1.0).
Resposta
Status:
200 OK
Corpo: JSON com o saldo disponível do cliente.
Exemplo de Resposta:
{
"balance": 1000.50
}
Campos da Resposta:
Campo
Tipo
Descrição
balance
number
Saldo disponível do cliente em reais (ex.: 1000.50 para R$ 1.000,50).
Exemplos de Código
curl -X GET https://sandbox.api.pagou.com.br/v1/customers/balance \
-H "X-API-KEY: sua_chave_api" \
-H "Content-Type: application/json" \
-H "User-Agent: MinhaLoja/1.0"
Tratamento de Erros
Código HTTP
Descrição
Possível Causa
Solução
400
Bad Request
Requisição malformada (ex.: cabeçalhos inválidos).
Verificar formato dos cabeçalhos.
401
Unauthorized
X-API-KEY
inválido ou ausente.
Verificar chave.
Exemplo de Resposta de Erro:
{
"error": "Customer not found"
}
Boas Práticas Técnicas
Segurança: Armazene
X-API-KEY
em variáveis de ambiente e use HTTPS para todas as requisições.Monitoramento: Registre todas as requisições e respostas (incluindo o valor de balance e código de status HTTP) em logs para auditoria e depuração.
Testes no Sandbox: Use https://sandbox.api.pagou.com.br/v1/customers/balance para simular consultas de saldo sem impacto em produção.
Last updated