Consultar Status da Cobrança

Consulte o status atual de uma cobrança para verificar se o pagamento foi confirmado.

GET/v1/charges/:id

Retorna o status e detalhes de uma cobrança específica

Parâmetros de URL

Parâmetro	Tipo	Descrição
`id`	string	ID da cobrança (`chargeId`) ou ID externo (`externalId`)

FlexibilidadeVocê pode consultar usando tanto o chargeId retornado pelo ActivePayments quanto o externalId do gateway de pagamento.

Resposta

Detalhes da respostaOs campos amount, netAmount e fee são retornados como string (serialização de Decimal — use parseFloat() antes de calcular). O campo status aqui é retornado em lowercase com mapeamento amigável (pending, paid, cancelled, failed), diferente dos endpoints de criação que retornam o enum interno em uppercase.

Valores de Status

Status	Descrição	Ação Recomendada
`pending`	Aguardando pagamento	Continue exibindo o QR Code
`paid`	Pagamento confirmado	Libere o produto/serviço
`cancelled`	Cobrança cancelada	Informe o cliente e ofereça nova cobrança
`failed`	Falha no processamento	Tente criar uma nova cobrança

Polling vs Webhooks

Existem duas formas de saber quando um pagamento foi confirmado:

Polling (não recomendado)

Consultar este endpoint periodicamente. Funciona, mas gera tráfego desnecessário e tem delay de até alguns segundos.

Webhooks (recomendado)

Configure um Webhook para receber notificações em tempo real quando pagamentos forem confirmados.

Limite de RateSe usar polling, respeite um intervalo mínimo de 5 segundos entre consultas para evitar bloqueio por rate limiting.

Códigos de Erro

Código	Descrição
`401`	Não autenticado - verifique suas credenciais
`404`	Cobrança não encontrada - verifique o ID informado

Próximo passoVeja como Listar Transações com filtros e paginação.

cURL
curl -X GET "https://api.ActivePayments.com.br/api/v1/charges/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: ApiKey ActivePayments_pk_xxx:ActivePayments_sk_xxx"

Node.js (fetch)
// Você pode usar o chargeId ou externalId
const chargeId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

const response = await fetch(`https://api.ActivePayments.com.br/api/v1/charges/${chargeId}`, {
  headers: {
    'Authorization': `ApiKey ${publicKey}:${secret}`,
  },
});

const data = await response.json();

if (data.data.status === 'paid') {
  console.log('Pagamento confirmado!');
  console.log('Pago em:', data.data.paidAt);
}

Response 200 OK
{
  "success": true,
  "data": {
    "chargeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "txid_abc123xyz",
    "amount": "150.50",
    "netAmount": "145.99",
    "fee": "4.51",
    "status": "paid",
    "customer": {
      "name": "João da Silva",
      "cpf": "12345678901",
      "email": "joao@email.com"
    },
    "createdAt": "2024-01-15T10:00:00.000Z",
    "paidAt": "2024-01-15T10:05:23.000Z"
  }
}