Solicitudes de pago
¿Qué son las solicitudes de pago?
Las Payment Requests son instrucciones de pago generadas mediante la API REST de Fluxis, firmadas y convertidas en NASPIP Tokens. Representan una forma estandarizada para que los comerciantes soliciten pagos a los usuarios en múltiples redes blockchain y activos.
Cada Payment Request incluye todos los detalles esenciales que un usuario necesita para completar un pago, como:
- red blockchain
- token
- importe
- dirección
- pedido opcional
—y toda esta información está firmada criptográficamente para garantizar autenticidad y verificación.
Estados de la solicitud de pago
Las solicitudes de pago avanzan por varios estados durante su ciclo de vida:
Estados principales
| State | Description | Duration |
|---|---|---|
pending | Creada vía flujo de checkout; el pagador aún no ha seleccionado un UAI | Hasta que se seleccione el UAI |
created | Dirección vault asignada; en espera de pago on-chain | 8 minutos |
expired | La solicitud de pago expiró sin pago | Permanente |
processing | Depósito on-chain detectado; en espera de finalidad | Variable |
completed | Pago recibido en su totalidad (o pago de importe abierto aceptado) | Permanente |
confirmed | Transacción de ledger creada tras pago exitoso | Permanente |
Estados de casos límite
Estos estados manejan escenarios especiales y requieren coordinación entre Fluxis y el comerciante:
| State | Description | Handling |
|---|---|---|
underpaid | Pago recibido pero el importe es menor al solicitado | Se requiere coordinación con el comerciante |
overpaid | Pago recibido pero el importe excede el solicitado | Se requiere coordinación con el comerciante |
failed | Ocurrió un error inesperado durante el procesamiento | Se requiere coordinación con el comerciante |
Los estados de casos límite son gestionados por Fluxis usando configuración específica del comerciante.
Patrón de integración recomendado
- Consulte
GET /v1/pos/{posID}/payment-request/{paymentRequestID}o suscríbase a webhooks a nivel de cuenta para cambios de estado. - Trate
processingcomo pago detectado; esperecompleted,underpaidooverpaid. confirmedindica que la plataforma ha creado la transacción de ledger.
Tiempos y expiración
Período de timeout: Las solicitudes de pago expiran 8 minutos después de asignar una dirección vault (estado created).
Período de gracia: Las transacciones transmitidas cerca de la expiración aún pueden detectarse mientras el vault permanezca en caché brevemente después de la expiración.
Crear una solicitud de pago
Ejemplo de solicitud básica
Code
Ejemplo de respuesta
Code
Ejemplo de respuesta de checkout alojado
Code
Use POST /v1/pos/{posID}/payment-request cuando el UAI del pagador se conoce de antemano. Use POST /v1/pos/{posID}/payment-request-checkout cuando el pagador deba elegir entre las payment_options del PoS. Ambos endpoints requieren un Point of Sale online_fixed.
Monitorear el estado del pago
Los comerciantes deben consultar regularmente el estado de la solicitud de pago para detectar pagos exitosos:
Ejemplo de verificación de estado
Code
Soporte multiactivo
Los comerciantes configuran múltiples UAIs en el Point of Sale (config.payment_options). Para permitir que los pagadores elijan su activo preferido, use el flujo de checkout alojado:
Code
La respuesta incluye un checkout_url y un token NASPIP con las payment_options disponibles. El pagador selecciona un UAI en el checkout; Fluxis asigna un vault y transiciona la solicitud de pago de pending a created.