Consultar Transação

Verifique o status atualizado de uma cobrança específica pelo seu ID.

GET/charges/:id

Descrição

Recupera os detalhes completos de uma cobrança gerada anteriormente. Útil para confirmar pagamentos, reconciliar transações ou recuperar o QR Code caso o cliente precise escanear novamente.

---

Parâmetros de URL

• :id string — Obrigatório O ID da cobrança retornado no momento da criação. Exemplo: A3F7C291

---

Resposta de Sucesso

Campo	Tipo	Descrição
id	string	ID único da cobrança
amount	number	Valor em reais
description	string	Descrição da cobrança
status	string	PENDING, PAID, EXPIRED ou CANCELLED
pix_code	string	Payload PIX Copia e Cola
fee	number	Taxa descontada
net_amount	number	Valor líquido após taxa
e2e_id	string | null	ID End-to-End do Banco Central — preenchido após pagamento
payer_name	string | null	Nome do pagador (quando disponível)
payer_document	string | null	CPF/CNPJ do pagador (quando disponível)
paid_at	string | null	Data/hora ISO 8601 do pagamento
expires_at	string | null	Data/hora de expiração
created_at	string	Data/hora de criação

---

Status Possíveis

Status	Significado
PENDING	Aguardando pagamento
PAID	Paga e confirmada — libere o produto/serviço
EXPIRED	Expirou sem pagamento
CANCELLED	Cancelada manualmente

---

Códigos de Erro

Código	Motivo
401	Token inválido ou ausente
404	Cobrança não encontrada ou pertence a outra conta
500	Erro interno

Requisição

curl https://api.nomadspay.com/charges/A3F7C291 \
  -H "Authorization: Bearer <SEU_CLIENT_SECRET>"

Resposta — Cobrança Paga (200 OK)

{
  "id": "A3F7C291",
  "amount": 100.50,
  "description": "Pedido #1234",
  "status": "PAID",
  "pix_code": "00020126870014br.gov.bcb.pix...",
  "fee": 4.02,
  "net_amount": 96.48,
  "e2e_id": "E60701190202607121200DY5A2EQIV4T",
  "payer_name": "João da Silva",
  "payer_document": "123.***.***-**",
  "paid_at": "2024-01-01T12:05:00Z",
  "expires_at": "2024-01-01T13:00:00Z",
  "created_at": "2024-01-01T12:00:00Z"
}

Resposta — Cobrança Pendente (200 OK)

{
  "id": "A3F7C291",
  "amount": 100.50,
  "status": "PENDING",
  "e2e_id": null,
  "payer_name": null,
  "paid_at": null
}

Exemplo em JavaScript

const chargeId = 'A3F7C291';

const response = await fetch(
  `https://api.nomadspay.com/charges/${chargeId}`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.NOMADS_SECRET}`
    }
  }
);

if (response.status === 404) {
  throw new Error('Cobrança não encontrada');
}

const charge = await response.json();

if (charge.status === 'PAID') {
  console.log('✅ Pago!', charge.e2e_id);
  // Libere o produto ou acesso aqui
} else if (charge.status === 'EXPIRED') {
  console.log('❌ Expirada — gere uma nova cobrança');
}

Exemplo em Python

import os, requests

charge_id = "A3F7C291"
secret = os.getenv("NOMADS_SECRET")

resp = requests.get(
    f"https://api.nomadspay.com/charges/{charge_id}",
    headers={"Authorization": f"Bearer {secret}"}
)

if resp.status_code == 404:
    raise Exception("Cobrança não encontrada")

charge = resp.json()

if charge["status"] == "PAID":
    print(f"✅ Pago! E2E: {charge['e2e_id']}")
elif charge["status"] == "EXPIRED":
    print("❌ Expirada")

---

O campo e2e_id

O e2e_id é o ID End-to-End emitido pelo Banco Central do Brasil para rastrear a transação PIX de ponta a ponta. Ele é preenchido automaticamente após o pagamento ser confirmado.

Use o e2e_id para conciliação financeira, comprovantes, ou para abrir chamados junto ao seu banco sobre uma transação específica.

---

❓ Dúvidas frequentes — Consultar Transação

Como saber com certeza se o pagamento foi confirmado?

Verifique os dois campos juntos — não apenas o status:

✅ Pagamento confirmado quando:

• "status": "PAID" E
• "e2e_id" está preenchido (ex: "E60701190...")
• "paid_at" tem uma data válida

Se status for PAID mas e2e_id for null, aguarde alguns segundos e consulte novamente — o webhook do banco pode estar em trânsito.

Recebi 404. O que significa?

Dois cenários possíveis:

1. ID errado — confirme que está usando exatamente o id retornado na criação da cobrança
2. Secret errada — cada credential só enxerga as cobranças da sua própria conta. Se estiver usando a secret de uma conta diferente da que gerou a cobrança, virá 404

Verifique se a secret usada na consulta é a mesma usada na criação.

Com que frequência devo consultar o status (polling)?

Se não tiver webhook configurado, o intervalo recomendado é:

Período após criação	Intervalo sugerido
0 a 5 minutos	A cada 5 segundos
5 a 30 minutos	A cada 15 segundos
Após 30 minutos	A cada 60 segundos
Após a expiração	Pare — o status não mudará mais

Recomendação: configure um webhook para eliminar o polling e receber a confirmação instantaneamente assim que o PIX for pago.

O status voltou para PENDING depois de PAID. Isso é possível?

Não. O status PAID é definitivo e irreversível na NomadsPay. Se você ver inconsistência no seu sistema, pode ser um problema de cache na sua aplicação. Sempre consulte a API em tempo real para confirmar o estado atual.

Posso listar todas as cobranças em vez de consultar uma por vez?

Sim. Use GET /charges com filtros opcionais:

# Listar apenas cobranças pagas
curl "https://api.nomadspay.com/charges?status=PAID&limit=50" \
  -H "Authorization: Bearer <SEU_CLIENT_SECRET>"

Parâmetros disponíveis: status, limit, offset.

O payer_name e payer_document sempre são preenchidos?

Não. O preenchimento depende do gateway e da instituição financeira do pagador. Algumas transações chegam sem esses dados — trate sempre como null por padrão no seu código e valide antes de usar.

Como usar o e2e_id para comprovante?

O e2e_id é o identificador oficial da transação PIX no sistema do Banco Central. Para gerar um comprovante, exiba:

• e2e_id — identificador da transação
• paid_at — data e hora do pagamento
• amount — valor pago
• payer_name — nome do pagador (se disponível)

Esse conjunto é suficiente para comprovação em disputas ou auditorias.