API Products (1.0.0)

Permite autenticar un usuario en el sistema SPIDI utilizando credenciales de acceso. Este endpoint es fundamental para obtener el token de autorización necesario para realizar operaciones posteriores en la API.

Funcionalidades principales:

• Autenticación segura: Valida las credenciales del usuario (short_name y password).
• Generación de token JWT: Retorna un token de acceso que debe utilizarse en requests posteriores.
• Control de sesión: El token tiene un tiempo de expiración definido para mayor seguridad.

Casos de uso típicos:

• Inicio de sesión de usuarios comercio.
• Obtención de token para operaciones API.
• Renovación de credenciales de acceso.
• Autenticación en aplicaciones integradas.

Una vez autenticado exitosamente, el token JWT debe incluirse en el header Authorization: Bearer {token} de todas las requests posteriores a la API.

Permite crear un nuevo agreement de pago que define las reglas de distribución y liquidación de las transacciones.

⚙️ Funcionalidades principales

• Distribución de pagos (Split): Define cómo se repartirán los fondos entre el comercio (owner) y sus partners o afiliados. El owner siempre existe y recibe automáticamente la diferencia no asignada a terceros.
• Liquidación bancaria inteligente: Permite dirigir los pagos hacia distintas cuentas bancarias de destino dependiendo del banco de origen del pagador.
• Medios de pago configurables: Determina qué tipos de pago acepta el acuerdo (immediate_debit, crypto, mobile_payment).
• split:
  • false: No aplica distribución; el owner recibe el 100 % del pago.
  • true: Usa porcentajes predefinidos que se aplican de manera uniforme en todas las transacciones. Solo se definen las participaciones de los terceros receptores; la diferencia restante se asigna automáticamente al owner, quien siempre debe recibir una parte del pago.

Casos de uso típicos

• Comercios que trabajan con partners y necesitan distribuir comisiones automáticamente.
• Marketplaces que deben dividir los pagos entre vendedores y la plataforma.
• Servicios que liquidan fondos en distintas cuentas según el banco de origen.
• Plataformas que requieren flexibilidad para definir la distribución por cada transacción.

Reutilización

Una vez creado, el agreement puede emplearse en múltiples sesiones de pago, asegurando consistencia en la distribución, control sobre la liquidación bancaria, y trazabilidad completa en todos los movimientos de fondos.

Permite crear una sesión de pago a través del botón de pago de SPIDI.Incluye el agreement_id para determinar las reglas de liquidación y split.

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)

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)

Permite crear una o múltiples sesiones de pago en forma de batch para solicitudes de pago. Cada item del batch contiene los campos de una sesión de pago más campos específicos para el manejo de vencimientos y notificaciones tardías.

Fuerza el cierre de una sesión de pago que se encuentra en estado pendiente.

Comportamiento según Estado Actual

• Si la sesión está PENDING, pasa a EXPIRED inmediatamente.
• Si ya estaba EXPIRED no hace nada.
• Si la sesión está PAID, NO puede expirarse (regla de negocio - retorna error 422).

Efecto sobre Paradas SPIDI

Si la sesión estaba asociada como activa en una Parada SPIDI, al pasar a expired deja de estar activa y queda en el histórico de la parada, por lo que el usuario podrá ver el mensaje que se le deja en user_message.

Notas y Buenas Prácticas

Paradas SPIDI

No necesitas llamar a /payment-stops/payment-sessions/batch con un item con op = remove; al expirar, la sesión sale sola del conjunto activo de cualquier parada a la que esté asociada (queda en histórico).

Trazabilidad

Usa message_audit para auditoría (quién, cuándo, por qué).

Lista todas las paradas (stops) del comercio autenticado, con soporte de búsqueda y filtros (por estado, título, referencia interna) y paginación. Es útil para construir listados administrativos, buscadores y reportes.

Crea una o múltiples Paradas SPIDI en un mismo request.

¿Qué son las Paradas SPIDI?

Las Paradas SPIDI son espacios únicos y permanentes asociados a cada cliente, donde este puede consultar, gestionar y pagar todas sus solicitudes de pago activas o históricas, sin necesidad de recibir nuevos solicitudes de pago cada vez.

Funcionan como un punto de acceso trazable y constante, ideal para relaciones comerciales continuas, suscripciones o pagos recurrentes, simplificando la experiencia tanto para el pagador como para la empresa.

Características principales

• URL permanente: Cada parada posee una stop_url única que el cliente puede visitar en cualquier momento
• Gestión centralizada: Desde esa URL, el cliente ve todas sus solicitudes de pago (pendientes, vencidas o completadas)
• Creación masiva: Permite crear de 1 a N paradas en un solo request, ideal para procesos de onboarding inicial
• Idempotencia: Soporta reintentos idempotentes mediante Idempotency-Key
• Asociación flexible: Puede vincularse a un cliente específico o a múltiples referencias según las necesidades de tu plataforma

Estados de una Parada

• Active: Existe al menos un enlace de pago activo; se muestran los pagos disponibles
• Empty: Sin solicitudes de pago activas; muestra el mensaje configurado en empty_state_message
• Disabled: Deshabilitada temporalmente, pero puede reactivarse
• Deleted: Eliminada definitivamente

Integración técnica

Se recomienda definir y mantener un campo internal_reference para cada recurso (cliente, contrato o factura), que servirá para conciliar y auditar operaciones entre tu sistema y SPIDI, y asociar solicitudes de pago con su Parada correspondiente.

Consulta los detalles y metadatos de una Parada SPIDI específica.

Devuelve información completa de la parada incluyendo:

• Identificadores (stop_id, stop_url)
• Metadatos configurables (stop_title, empty_state_message, status)
• Referencia interna (internal_reference)
• Solo solicitudes de pago activas (links_active)

Para consultar el historial completo de solicitudes de pago (incluyendo pagados y expirados), utiliza el endpoint /api/v1/ext/payment-stops/{stop_id}/payment-sessions.

Actualiza los metadatos de una Parada SPIDI existente.

Permite modificar:

• stop_title: Título visible de la parada
• status: Estado de la parada (active o disabled)
• empty_state_message: Mensaje mostrado cuando no hay solicitudes de pago activas

Los campos stop_id, stop_url e internal_reference no pueden modificarse una vez creada la parada.

Elimina definitivamente una Parada SPIDI.

⚠️ Importante:

• La eliminación es permanente y no se puede revertir
• No se permite eliminar una parada que tenga solicitudes de pago activas asociadas; primero debes removerlos o expirarlos
• La operación es idempotente: múltiples llamadas con la misma Idempotency-Key no crearán duplicados

** Recomendación:** En lugar de eliminar, considera deshabilitar la parada usando el endpoint PATCH con status: "disabled". Esto permite reactivarla en el futuro si es necesario.

Consulta el historial completo de solicitudes de pago asociados a una Parada SPIDI.

Devuelve la lista completa de solicitudes de pago asociados a un stop_id, incluyendo:

• Sesiones de Pago Activas (pending)
• **Sesiones de Pago Pagadas ** (paid)
• Sesiones de Pago Expiradas (expired)

Soporta filtros avanzados por estado, rango de fechas y paginación para manejar colecciones grandes.

Diferencia con GET /payment-stops/{stop_id}:

• El endpoint básico solo devuelve solicitudes de pago activas
• Este endpoint devuelve el historial completo con opciones de filtrado y paginación

Ejecuta operaciones en lote para asociar/desasociar/reemplazar/limpiar sesiones de pago (session_id) visibles en una o varias Paradas (stop_id) en una sola llamada.

Operaciones soportadas:

• add: Agrega 1..N session_id como activos (si ya estaban, es no-op y se reportan en already_present)
• remove: Desasocia 1..N session_id activos (si no estaban activos, se reportan en not_active o not_found)
• replace: Sustituye atómicamente el conjunto activo por session_ids. Con lista vacía ⇒ clear
• clear: Elimina todos los activos (la Parada puede quedar en estado Empty)

Características:

• Idempotente mediante encabezado Idempotency-Key (TTL: 24 horas)
• Cada ítem se procesa de forma independiente
• El resultado se devuelve por Parada
• Rate limit: 100 requests/minuto por comercio

Notas importantes:

• Solo sesiones pending pueden activarse (add/replace). Las sesiones paid/expired pasan a histórico automáticamente
• replace con lista vacía equivale a clear (limpieza atómica)
• Usa siempre Idempotency-Key en operaciones en lote
• Máximo 100 items por batch

Define el orden de visualización de los solicitudes de pago activas (derivados de sesiones session_id) dentro de una o varias Paradas (stop_id) en una sola llamada.

Características:

• No agrega ni quita sesiones; solo cambia el orden
• Idempotente mediante Idempotency-Key (TTL: 24 horas)
• Control de concurrencia opcional mediante order_version (recomendado)
• Rate limit: 100 requests/minuto por comercio

Modos de operación:

• append (default): reordena las sesiones listadas arriba y cualquier activa no listada queda al final manteniendo su orden relativo actual
• strict: la lista debe representar exactamente el conjunto de activos; si falta alguna activa o sobra alguna no activa, se devuelve error por ítem

Notas importantes:

• Separación de responsabilidades: usa reorder solo para ordenar. Para agregar/quitar/sustituir, utiliza el batch de operar solicitudes de pago
• Idempotencia siempre: envía Idempotency-Key; misma clave + mismo payload ⇒ misma respuesta
• Máximo 100 items por batch

Devuelve, en una sola llamada, los solicitudes de pago activas (derivados de sesiones pending) para varias Paradas (stop_id).

Incluye paginación por Parada, filtros básicos y posibilidad de limitar campos para reducir payload.

¿Por qué POST para "leer"? Acepta listas grandes de stop_id (hasta 200) y tokens de paginación por Parada; un GET se quedaría corto por límites de longitud de URL. Este patrón es común en APIs modernas (Google Cloud, AWS) para queries complejas.

Características:

• Optimizado para UI cliente - devuelve solo activos por defecto (status=pending)
• Paginación cursor-based por parada
• Rate limit: 100 requests/minuto por comercio
• Máximo: 200 stop_ids por request

Notas importantes:

• Si necesitas histórico, usa status: "historical" o include_history: true en el request
• Para más de 200 stops, realiza múltiples requests
• Este endpoint es idempotente (lectura) y cacheable

Endpoint para la creación de un nuevo partner en el sistema.

Crea un agreement de recepción de split —un destinatario final que puede recibir montos distribuidos desde otros usuarios que apliquen un split en sus acuerdos de pago.

Al crear este recurso, SPIDI genera un identificador único global (split_recipient_agreement_id) con prefijo semántico rcv_, que debes compartir con los usuarios que deseen enviar parte de sus pagos hacia tu cuenta.

Este agreement no admite splits adicionales: su única función es definir el ruteo de la liquidación, determinando la cuenta bancaria destino.

Características

• Identificador global retornado como split_recipient_agreement_id (UUID SPIDI)
• Enrutamiento con fallback a default_bank_account_id
• Referenciable desde acuerdos de distribución vía split_recipient_agreement_id

Notas de Validación

• Debe existir siempre default_bank_account_id
• En rules, cada origin_bank_code no puede repetirse
• Si en runtime no hay match de origin_bank_code, se utiliza el default_bank_account_id
• Si no hay match y falta default_bank_account_id → error

Idempotencia

Usa siempre Idempotency-Key (UUID v4). Reenviar el mismo POST con igual payload devolverá el mismo resultado sin duplicar efectos.

Se produce cuando se crea una nueva sesión de pago. Esta sesión queda disponible para que el pagador realice el pago correspondiente. Se enviará una notificación de este evento mediante un webhook cuando se crea una nueva sesión de pago.

Se produce cuando el pagador completa exitosamente el pago de una sesión, confirmándose la recepción de los fondos. Se enviará una notificación de este evento mediante un webhook cuando el pagador completa exitosamente el pago de una sesión

Advertencia: Este endpoint está en desarrollo

Se produce cuando ocurre un fallo en el intento de acreditar los fondos a un receptor esperado del pago. Se enviará una notificación de este evento mediante un webhook por cada intento fallido. El sistema realizará reintentos automáticos hasta lograr la acreditación exitosa.

Advertencia: Este endpoint está en desarrollo

Los fondos han sido acreditados a uno de los receptores esperados del pago. Se enviará una notificación de este evento mediante un webhook por cada receptor esperado y únicamente cuando el pago contempla múltiples acreditaciones (split).

La totalidad de los fondos ha sido acreditada al receptor o a los receptores esperados del pago. Se enviará una notificación de este evento mediante un webhook cuando el pago contemple una única acreditación, se enviara el evento cuando se complete dicha acreditación. En caso de múltiples acreditaciones (split), se emitirá una sola vez al completarse exitosamente la totalidad de las acreditaciones.