# 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 | ::::note Los estados de casos límite son gestionados por Fluxis usando configuración específica del comerciante. ::::: ### Patrón de integración recomendado 1. Consulte `GET /v1/pos/{posID}/payment-request/{paymentRequestID}` o suscríbase a [webhooks a nivel de cuenta](/es/docs/developers/webhooks) para cambios de estado. 2. Trate `processing` como pago detectado; espere `completed`, `underpaid` o `overpaid`. 3. `confirmed` indica que la plataforma ha creado la transacción de ledger. ## Tiempos y expiración ::::info **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 ```json POST /v1/pos/{posID}/payment-request { "reference_id": "order-12345-FLX25", "amount": "49.99", "unique_asset_id": "npolygon_t0xc2132D05D31c914a87C6611C10748AEb04B58e8F", "order": { "total": "49.99", "coin_code": "USD", "description": "Premium Subscription", "items": [ { "description": "Premium Subscription", "quantity": 1, "unit_price": "49.99", "amount": "49.99", "coin_code": "USD" } ] } } ``` ### Ejemplo de respuesta ```json { "status": "success", "data": { "id": "180ede28-2968-4ac7-8e81-ca446f201949", "reference_id": "order-12345-FLX25", "status": "created", "token": "naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI...more-token...EwLTAy", "expiration": 1759397652 } } ``` ### Ejemplo de respuesta de checkout alojado ```json { "status": "success", "data": { "id": "180ede28-2968-4ac7-8e81-ca446f201949", "reference_id": "order-12345-FLX25", "status": "pending", "token": "naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI...", "checkout_url": "https://checkout.fluxis.us/pos/{posID}/payment/{paymentRequestID}", "expiration": null } } ``` ::::note 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 ```json GET /v1/pos/{posID}/payment-request/{paymentRequestID} { "status": "success", "data": { "id": "180ede28-2968-4ac7-8e81-ca446f201949", "reference_id": "order-12345-FLX25", "status": "completed", "expiration": 1759397652, "amount": "49.99", "expected_amount": "49.99", "address": "0x1234567890123456789012345678901234567890", "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", "reference_asset_id": "USD", "reference_amount": "49.99", "exchange_rate": "1", "point_of_sale_id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:33:15Z" } } ``` ## Soporte multiactivo Los comerciantes configuran múltiples [UAIs](/es/docs/key-concepts/uai) en el **Point of Sale** (`config.payment_options`). Para permitir que los pagadores elijan su activo preferido, use el flujo de checkout alojado: ```json POST /v1/pos/{posID}/payment-request-checkout { "reference_id": "order-12345-FLX25", "amount": "49.99", "coin_code": "USD", "order": { "total": "49.99", "coin_code": "USD", "description": "Premium Subscription" } } ``` 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`.