Consultar Sesión

Descripción

Este endpoint permite consultar el estado actual de una sesión de pago y sus datos esenciales, generada mediante una solicitud de pago o botón de pago.

Este endpoint es la fuente oficial y confiable para verificar si la sesión de pago fue completada con éxito (paid), rechazada (failed), expirada (expired) o está pendiente (pending).

Origen de la Sesión

Una sesión de pago puede crearse mediante un Botón de pago o una Solicitud de pago, cada una con su propio endpoint de creación. Sin embargo, para consultar una sesión de pago —sin importar cómo haya sido creada— se utiliza el mismo endpoint de consulta. En la respuesta, existe un campo session_origin que revelará si fue creada por botón de pago (button) o por solicitud (request).

En los casos donde la sesión fue creada a través de un Botón de pago, el campo status puede tener un valor adicional: failed.

Notas Importantes

Verificación de Pagos (Backend Obligatorio)

No asumas paid solo por redirección; consulta este endpoint desde tu servidor antes de liberar servicios o productos.

Liquidación al Receptor

Tras paid, la liquidación al receptor puede tardar unos segundos; en ese caso receiver_credits y receiver_credits_summary pueden venir null temporalmente.

Independientemente de si la liquidación al receptor aún no ha ocurrido, se considera en todo su concepto amplio que el pago fue realizado exitosamente, por lo que se debe continuar con la entrega del servicio o producto sin ningún problema.

La liquidación al receptor es un proceso interno y, aunque puede demorar pocos segundos o hasta 2 minutos, no existe riesgo de fallo. En los términos y condiciones se especifica esta garantía, que constituye un derecho causado e irrevocable según los términos acordados.

Por lo tanto: En caso de que tengas control, no retengas ni retrases la prestación del servicio al pagador mientras esperas la liquidación.

Consulta de Datos de Liquidación

Si necesitas mostrar o procesar datos de la liquidación, consulta el endpoint de status periódicamente hasta que los campos de receiver_credits estén presentes.

Opcionalmente, si implementaste un webhook, recibirás una notificación automática en tu API cuando la liquidación se haya completado y los datos estén disponibles (eventos payment.paid / payment.settled).

URL del Comprobante

Recuerda que se incluye el URL del comprobante exitoso (spidi_transaction_url), que debe ser mostrado al usuario de una forma u otra.

Pagos con Criptomonedas

Si payment_method es "crypto", el objeto crypto_details contendrá información específica del pago cripto
Si payment_method es distinto a "crypto", entonces crypto_details será null
En caso de pago con crypto, si está en "paid_pending", entonces los objetos payment_details, receiver_credits y receiver_credits_summary estarán presentes con valores null

Split de Pagos

Si no se generó un split, entonces el objeto de receiver_credits tiene un solo elemento
Si existió el split, deben haber al menos dos elementos en receiver_credits

Estados Vigentes

pending: Sesión creada, esperando que el usuario complete el pago
paid: Pago completado exitosamente
expired: Sesión expirada por inactividad o manualmente
failed: Pago fallido (solo para sesiones creadas con botón de pago)

Endpoint

GET /api/v1/ext/payment-sessions/status/:session_id

Autenticación Requerida

Bearer / Token: BearerAuth

Requiere el uso de el token obtenido en /auth/login

Esquema: bearer (JWT)

Request

Responses

Consulta exitosa del estado de la sesión