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.

500

Internal Server Error

Erro interno da API.

Tentar novamente e contatar [email protected].

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