Conciliación y runbook de operaciones

La anulación, el reembolso, los recibos y el listado ya existen, así que recuperarse es posible - pero solo si decidiste de antemano qué hacer. Definí estos caminos antes de lanzar.

Persistí lo suficiente para poder recuperarte. Guardá roki_payment_id, external_reference, status, total, checkout_url, expires_at y last_event_id en tu orden. Copiá también el id de tu orden dentro de metadata, así un pago que se inspeccione en el portal se puede rastrear sin tu base de datos.

Barré las órdenes pendientes de forma programada. Volvé a consultar los ids guardados de las órdenes que sigan en pending pasado cierto umbral, y de cualquier orden que ya pasó su expires_at. Con el endpoint de listado también podés barrer al revés - GET /payments?status=paid&from=... - y agarrar pagos que ya están liquidados en ROKI pero siguen abiertos en tu sistema porque se perdió un webhook.

Manejá los estados terminales que llegan tarde. expired, voided, refunded y partially_refunded pueden aparecer en cualquier momento - incluso desde una persona actuando en el portal, sin ninguna llamada a la API de tu parte. Un manejador que asuma que "solo mis propias llamadas cambian el estado" va a estar equivocado.

Recuperate de una creación que se cayó por timeout. Si una petición de creación no devuelve respuesta, no crees un segundo pago. Reintentá una vez con la misma Idempotency-Key: si el primer intento llegó a ROKI, te devuelve ese pago; si no, se crea ahora.

Alertá sobre esto. 401 repetidos (una llave rotada o rota), picos de 422 (un deploy mandando un payload malo), fallas de firma de webhook (secreto equivocado, o el manejo del cuerpo crudo roto por un cambio de middleware), y órdenes pagadas en ROKI pero todavía pendientes localmente (webhooks que no llegan).

Automatizá las reversiones, pero respetá el orden. La anulación aplica antes de la liquidación y devuelve el monto completo de inmediato; el reembolso aplica después, y puede ser parcial. Implementá la reversión así: probá anular, y si te la rechazan porque ya está liquidada o porque no es anulable, reembolsá en su lugar. Las dos también están disponibles para una persona en el portal, y las dos emiten webhooks en cualquier caso.