Consultar depósito

GET /api/v1/valepix/deposits/{transaction_id}

Retorna o estado e os dados de pagamento de um depósito disponível para a integração autorizada.

Autenticação

Envie um API token ativo no header Authorization.

Authorization: Bearer <VALEPIX_API_TOKEN>
Accept: application/json

Path params

Parâmetro	Tipo	Obrigatório	Descrição
transaction_id	string	Sim	Identificador retornado ou aceito na criação do depósito

Exemplo curl

curl --request GET \
  --url "https://routes.valepix.com.br/api/v1/valepix/deposits/$TRANSACTION_ID" \
  --header "Authorization: Bearer $VALEPIX_API_TOKEN" \
  --header "Accept: application/json"

Response

HTTP 200 OK.

{
  "success": "success",
  "data": {
    "transaction_id": "00000000-0000-4000-8000-000000000501",
    "status": "COMPLETED",
    "amount": 100000,
    "description": "Depósito",
    "fee_amount": 250,
    "payment_info": {
      "amount": 100250,
      "expiration_date": "2026-07-24T23:59:59Z"
    }
  }
}

amount é o valor líquido do depósito, fee_amount é a taxa e payment_info.amount é o total da cobrança.

Como usar o resultado

• Consulte com intervalo e backoff; não faça polling contínuo.
• PENDING ou SCHEDULED indica que ainda não há confirmação final.
• COMPLETED indica pagamento concluído.
• FAILED, CANCELLED ou EXPIRED são estados finais sem conclusão do pagamento.
• Confirme o valor disponível em Consultar saldos antes de finalizar uma distribuição.

Erros comuns

HTTP	Quando acontece	Ação recomendada
400	transaction_id inválido	Conferir o identificador enviado na URL
401	Token ausente, inválido, expirado ou revogado	Conferir o header Authorization
403	Token sem acesso ao recurso solicitado	Confirmar token com a ValePix
404	Depósito não encontrado	Conferir o transaction_id e o ambiente
429	Limite de chamadas excedido	Reduzir a frequência das consultas e aplicar backoff
500, 502, 503, 504	Falha temporária na consulta	Tentar novamente com backoff