Cómo confirmar que un cobro se pagó

El error común

Entregar el servicio porque el cliente “llegó a la página de gracias”. Esa URL puede abrirse sin pagar, reenviarse a otra persona o cargarse después de cerrar el checkout. En Pagos Express la página de éxito consulta el estado real del pago antes de mostrar la palomita, pero tu backend no debería depender de un navegador ajeno.

Qué sí confirma

• El pago en succeeded: GET /v1/payments/{id} o GET /v1/payments?status=succeeded.
• El enlace en paid, con paidPaymentId apuntando a ese pago.
• Un webhook payment.succeeded o payment_link.paid cuya firma Pagos-Signature verificaste con tu secreto.

pending significa que el checkout se creó y el cliente no terminó. failed y canceled dejan el enlace pagable si sigue vigente. Ninguno de los tres es dinero recibido.

Si un webhook se perdió

Un worker de conciliación revisa los pagos pendientes de forma continua, así que normalmente no tienes que hacer nada. Si necesitas certeza ahora, POST /v1/payments/{id}/sync consulta la pasarela y devuelve outcome: updated, pending, retrying o needs_review. Nunca reembolsa ni cancela nada.

Pagos fuera del checkout

Si el cliente hizo una transferencia SPEI o pagó en efectivo, el comercio lo registra con Marcar como pagado desde el dashboard, la API (mark_paid) o el agente. El enlace pasa a paid, el pago queda como provider: manual en succeeded y se disparan los mismos webhooks que con una tarjeta. Se puede adjuntar el comprobante.

Recomendación

Trata succeeded como la única verdad, deduplica webhooks por id y guarda tu número de pedido en la metadata del enlace: viaja en el pago y en cada evento, así relacionas el cobro con tu sistema sin otra consulta. Los detalles están en las guías de pagos y webhooks.