Consultar pagamento

A Allya Payments expõe duas formas de consultar um pagamento já criado:

• GET /v1/payments/:id: busca pelo ID interno retornado em POST /v1/payments.
• GET /v1/payments?externalId=...: busca pelo identificador do seu sistema (idempotência).

Ambas usam a mesma autenticação por API key e ficam escopadas ao ambiente da chave: uma chave sk_test_ só lê pagamentos de sandbox, e sk_live_ só lê pagamentos de produção.

A resposta tem o mesmo formato de POST /v1/payments.

O bloco customer retorna name, email e documentLast4. A Allya não retorna CPF/CNPJ completo porque o documento é persistido apenas como hash + últimos 4 dígitos.

Buscar por ID interno

const response = await fetch(
  `https://payments-api.allyasolutions.com/v1/payments/${paymentId}`,
  {
    headers: { Authorization: `Bearer ${process.env.ALLYA_API_KEY}` },
  },
);

if (response.status === 404) {
  // Pagamento não existe nesse ambiente.
}

const payment = await response.json();
console.log(payment.status); // "paid", "pending", "failed", ...

Buscar por externalId

Útil para reconciliação quando seu sistema só persistiu o externalId e não o id interno da Allya, ou para conferir se uma cobrança já foi criada antes de tentar de novo.

const response = await fetch(
  `https://payments-api.allyasolutions.com/v1/payments?externalId=${encodeURIComponent("pedido_123")}`,
  {
    headers: { Authorization: `Bearer ${process.env.ALLYA_API_KEY}` },
  },
);

if (response.status === 404) {
  // Nenhum pagamento com esse externalId neste ambiente.
}

const payment = await response.json();

Códigos de resposta

Diferenças entre as duas formas

Observações

• A consulta não atualiza o status no gateway: devolve apenas o que está persistido na Allya. Para reconciliar quando um webhook não chegou, use POST /v1/payments/:id/sync.
• Esta rota retorna apenas o resumo público do pagamento. Para histórico de eventos e webhooks enviados, use o painel em Pagamentos → detalhe.

Veja também

• Sincronizar pagamento: quando o estado local diverge do gateway.
• Status de pagamento: significado de cada status.
• Idempotência: papel do externalId na consulta.
• Consultar assinatura: equivalente para recorrência.