Conceitos

Operações 202 e UNKNOWN

Toda escrita financeira (cobrança, estorno, assinatura, plano, dois cartões, transferência) é registrada como intenção e executada no provedor de forma assíncrona. A resposta 202 traz a operação que você acompanha.

Por que 202

A chamada ao provedor de pagamentos acontece fora da sua requisição, num processo que reserva a operação, envia uma única vez com uma referência estável e registra cada tentativa. Assim, uma falha de rede no meio do caminho nunca vira cobrança em dobro.

Resposta 202 de POST /v1/payments

{
  "id": "op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "status": "ACCEPTED",
  "kind": "CREATE_PAYMENT",
  "resourceId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
  "statusUrl": "/v1/operations/op_01JDY8D1B2C3D4E5F6G7H8J9KD",
  "nextAction": "WAIT",
  "createdAt": "2026-11-13T13:00:00.000Z"
}

Estados

Estados da operação
status	Significado	O que fazer
`ACCEPTED`	Registrada, aguardando envio.	Aguarde.
`DISPATCHING`	Em envio ao provedor.	Aguarde.
`SUCCEEDED`	O provedor aceitou. O recurso (resourceId) existe.	Siga o fluxo (ex.: mostrar o QR Pix).
`FAILED`	Recusa conclusiva; nada foi criado ou foi recusado.	Veja `error` e `nextAction`.
`UNKNOWN`	O resultado no provedor ainda não foi provado (timeout ou rede depois do envio).	Aguarde: a plataforma consulta o provedor pela referência e resolve. Não crie outra cobrança.
`MANUAL_REVIEW`	A consulta não conseguiu provar o resultado dentro do prazo.	Fale com o suporte com o id da operação.

Próxima ação
nextAction	Quando
`WAIT`	A operação ainda não terminou.
`COMPLETE_3DS`	O emissor pediu autenticação 3DS. Leve o pagador a `challengeUrl`; a cobrança continua pendente até o resultado.
`UPDATE_PAYMENT_METHOD`	Cartão recusado: peça outro cartão (nova captura) e crie nova cobrança.
`CONTACT_SUPPORT`	Revisão manual.
`NONE`	Nada a fazer.

UNKNOWN não é falha

Como acompanhar

Webhooks (preferido): payment.created, payment.confirmed, payment.failed e, para liberar o produto, order.payment_completed.
Consulta: GET /v1/operations/{id} (o statusUrl da resposta), com intervalo crescente. Útil para retomar depois de recarregar a página.

SDK: aguardar sem repetir a escrita

import { EcliptaPay, OperationTimeoutError } from "@eclipta-pay/sdk";

const op = await eclipta.createPayment({ orderId, method: "PIX", dueDate: "2026-11-20" });
try {
  const final = await eclipta.waitForOperation(op, { timeoutMs: 60_000 });
  if (final.nextAction === "COMPLETE_3DS") redirecionar(final.challengeUrl!);
} catch (e) {
  if (e instanceof OperationTimeoutError && e.operation.status === "UNKNOWN") {
    // Resultado em verificação pela plataforma: mostre "processando" e espere o webhook.
  } else throw e;
}

Próximo: Erros