Skip to main content
Todo pago pasa por una serie predecible de estados — desde una reserva inicial de fondos hasta la liquidación final o la cancelación. Therius te da dos formas de mover un pago a través de ese ciclo de vida: un flujo de un paso que autoriza y captura en una sola llamada, y un flujo de dos pasos que separa la autorización de la captura. Saber qué flujo usar, y cuándo aplica cada operación posterior al pago, te ahorrará casos límite y cargos disputados.

​
Flujo de un paso: compra

Usa POST /payment/purchase cuando puedas cumplir el pedido de inmediato — descargas digitales, suscripciones SaaS y cualquier producto que entregues en el momento en que se completa el pago. Un solo viaje de ida y vuelta reserva los fondos y los liquida de una vez. La respuesta lleva status: "captured" y un id — el identificador del pago.

​
Flujo de dos pasos: autorizar → capturar

Usa POST /payment/authorization para reservar fondos sin liquidarlos. Es el flujo correcto cuando necesitas confirmar la disponibilidad antes de cumplir — por ejemplo, bienes físicos que pueden agotarse, o reservas de hotel donde confirmas la habitación antes de cobrar.
La respuesta de autorización incluye un id (un UUID). Ese id es cómo diriges el pago en cada operación de seguimiento — pásalo como el segmento de ruta {id}. Aplican algunas reglas:
  • La ventana de autorización suele ser de 7 días, aunque algunos adquirentes permiten ventanas más cortas o más largas. Si no capturas dentro de la ventana, la autorización expira y los fondos se liberan automáticamente.
  • La captura parcial está disponible. Puedes capturar cualquier monto hasta el monto autorizado. Por ejemplo, autoriza 100ycaptura100 y captura 80 si un artículo está agotado.
  • Una vez que un pago se captura no puedes capturar de nuevo — usa el reembolso para cualquier ajuste.

​
Reembolso

Llama a POST /payment/{id}/refund para devolver fondos de un pago capturado. Los reembolsos pueden ser totales o parciales, y puedes emitir varios reembolsos parciales mientras el total acumulado no supere el monto capturado originalmente.
Un reembolso parcial de 5.00sobreunpagode5.00 sobre un pago de 19.99 devuelve la diferencia al titular de la tarjeta. El estado del pago pasa a refunded una vez que se procesa un reembolso total.

​
Cancelar

Llama a POST /payment/{id}/cancel para anular un pago autorizado antes de que se capture. Los fondos se liberan de inmediato y nunca se le cobra al cliente. No puedes cancelar un pago que ya se capturó — llama a POST /payment/{id}/refund en su lugar.

​
Cancelación o reembolso automático

Si no estás seguro de si un pago está en estado authorized o captured, llama a POST /payment/{id}/cancel_or_refund. Therius verifica el estado actual y realiza la operación correcta automáticamente — una cancelación si el pago está autorizado, un reembolso total si está capturado.

​
Estados del pago

​
Máquina de estados

​
id, paymentCode y orderCode

orderCode y paymentCode son campos de referencia únicamente — se devuelven en las respuestas y los webhooks. Consulta acepta el id o el paymentCode en su ruta. Pero capture, refund, cancel y cancel_or_refund toman solo el id. Guarda siempre el id de la respuesta de autorizar/comprar y úsalo para esas llamadas.