# Crear y monitorear solicitudes de pago ## El flujo de pago Entender el flujo de pago completo te ayuda a integrar Fluxis de forma efectiva en tu aplicación: ```mermaid sequenceDiagram participant M as Your App participant F as Fluxis API participant C as Customer participant B as Blockchain M->>F: Create Payment Request F-->>M: Payment Details + NASPIP Token M->>C: Display Payment (QR/Link) C->>B: Send Payment B->>F: Transaction Detected F->>M: Webhook: Processing B->>F: Transaction Confirmed F->>M: Webhook: Completed M->>C: Order Confirmed ``` ### Desglose del flujo 1. **Tu app crea una solicitud de pago** vía API de Fluxis para un monto específico 2. **Fluxis devuelve los detalles de la solicitud de pago** incluyendo un token NASPIP 3. **El cliente ve la solicitud de pago** como código QR o enlace de pago 4. **El cliente paga** usando su billetera cripto 5. **Fluxis detecta el pago** en la blockchain y te notifica 6. **La transacción se confirma** y cumples el pedido ## Crear una solicitud de pago Para crear una solicitud de pago, necesitarás:

📋 Información requerida

Puedes crear tu primera solicitud de pago en nuestro [API Playground - Payment Request](/api/point-of-sale#create-point-of-sale-payment-request). Alternativamente, usa **hosted checkout** (`POST /v1/pos/{posID}/payment-request-checkout`) para recibir una `checkout_url` a la que puedes redirigir clientes sin construir tu propia UI NASPIP. ### El token NASPIP El token NASPIP es una cadena firmada criptográficamente que contiene todas las instrucciones de pago: ``` naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI1LTEwLTI... ``` Este token puede: - **Codificarse como código QR** para escaneo con billetera móvil - **Compartirse como enlace de pago** para billeteras web/escritorio - **Compartirse por billeteras con NFC** para pago por proximidad u offline ::::tip **Opciones de visualización** La mayoría de comercios muestran el token NASPIP como código QR para escaneo móvil fácil. Codifica el campo `token` de la respuesta create-payment-request como imagen QR en tu app. :::: ### Tokens NASPIP basados en URL Algunos tokens incorporan una `url` en lugar de instrucciones de pago inline. Usa `POST /v1/naspip/read` con el token — cuando el payload contiene una URL sin `payment_options`, Fluxis resuelve las instrucciones de pago obteniendo esa URL del lado del servidor antes de devolver los datos decodificados. ## Estados de solicitud de pago Las solicitudes de pago progresan por distintos estados durante su ciclo de vida: ### Diagrama de transición de estados ```mermaid stateDiagram-v2 [*] --> created: Payment Request Created created --> expired: 8 minutes timeout created --> processing: Payment Detected processing --> completed: Correct Amount processing --> underpaid: Amount < Expected processing --> overpaid: Amount > Expected processing --> failed: Error Occurred completed --> [*] expired --> [*] underpaid --> [*] overpaid --> [*] failed --> [*] ``` ### Descripción de estados | Estado | Significado | Qué hacer | | ------------ | -------------------------------------------------- | ----------------------------------------------- | | `created` | Esperando pago (activo ~8 minutos) | Mostrar al cliente, monitorear cambios | | `processing` | Pago detectado, esperando confirmación blockchain | Seguir monitoreando, informar al cliente | | `completed` | Pago recibido y confirmado | Cumplir pedido, cerrar solicitud de pago | | `expired` | Tiempo de espera agotado sin pago | Ofrecer crear nueva solicitud de pago | | `underpaid` | Se recibió menos del monto esperado | Contactar soporte para resolución | | `overpaid` | Se recibió más del monto esperado | Contactar soporte para resolución | | `failed` | Error inesperado durante el procesamiento | Contactar soporte; puede necesitarse nueva solicitud | ::::info **Casos límite** Los estados `underpaid`, `overpaid` y `failed` son casos límite que requieren coordinación con el soporte de Fluxis según tus requisitos de negocio. Más información aquí: [Flujos de pago - Casos límite](/es/docs/payment-flows/edge-cases). :::: ## Monitorear el estado del pago Después de crear una solicitud de pago, debes monitorear su estado para saber cuándo se recibe el pago. Hay dos enfoques: ### Opción 1: Polling Consulta periódicamente el estado de la solicitud de pago llamando al endpoint de estado. **Endpoint:** `GET /v1/pos/{posID}/payment-request/{paymentRequestID}` Pruébalo en nuestro [API Playground - Get Payment Request](/api/point-of-sale#get-payment-request). #### Estrategia de polling

Intervalo de polling recomendado:

**Ventajas:** - Simple de implementar - Funciona con cualquier infraestructura - No requiere configuración adicional **Desventajas:** - No es en tiempo real - Crea sobrecarga en la API - Puede perder cambios de estado rápidos ### Opción 2: Webhooks Configura webhooks a nivel de cuenta para recibir notificaciones cuando cambie el estado del pago. Este es el **enfoque recomendado** para sistemas de producción. **Endpoint:** `POST /v1/account/{accountID}/webhook` Pruébalo en el [API Playground — Create webhook](/api/webhooks#create-webhook). #### Configuración de webhook Registra una URL HTTPS completa y establece `event_type` en `payment_request`: ```json { "url": "https://your-server.com/webhooks/fluxis", "event_type": "payment_request" } ``` Fluxis genera el `secret` de firma y lo devuelve una vez en la respuesta de creación. Los webhooks se disparan para `processing`, `completed`, `underpaid` y `overpaid` — no para `expired` o `failed`. Consulta la [guía de Webhooks](/es/docs/developers/webhooks) y [Verificación de firma de webhook](/es/docs/developers/webhook-signature-verification). Después del registro, valida tu manejador con `POST /v1/account/{accountID}/webhook/{webhookID}/test`. **Ventajas:** - Notificaciones en tiempo real - Sin sobrecarga de polling - Eficiente y escalable - Arquitectura orientada a eventos **Desventajas:** - Requiere endpoint público - Necesitas implementar un manejador de webhook - Debes verificar firmas de webhook ::::tip Mejor práctica Usa webhooks para producción y polling como respaldo. Implementa ambos métodos para no perder nunca una confirmación de pago. :::: ## Manejar distintos escenarios ### Escenario 1: Pago exitoso 1. El cliente escanea el código QR o hace clic en el enlace de pago 2. El cliente confirma el pago en su billetera 3. El pago aparece en la blockchain 4. El estado cambia a `processing` 5. La transacción recibe confirmaciones suficientes 6. El estado cambia a `completed` 7. Cumples el pedido **Tu acción:** Cumple el pedido cuando el estado sea `completed`. ### Escenario 2: Solicitud de pago expirada 1. Pasan ~8 minutos sin pago 2. El estado cambia a `expired` 3. La solicitud de pago ya no es válida **Tu acción:** Ofrece al cliente la opción de crear una nueva solicitud de pago. ### Escenario 3: Transacción lenta 1. El cliente inicia el pago cerca de la expiración 2. La transacción se transmite pero no se confirma antes del tiempo límite 3. El período de gracia de Fluxis procesa la transacción tardía 4. El estado se actualiza a `processing` y luego `completed` **Tu acción:** Continúa monitoreando incluso después de la expiración por 2-3 minutos adicionales. ## Mejores prácticas ### 1. Usa siempre Reference IDs

Incluye tu ID interno de pedido o transacción en el campo{" "} reference_id. Esto facilita mucho la conciliación y depuración.

### 2. Muestra información de pago clara

Muestra a los clientes:

### 3. Maneja la expiración con elegancia

No abandones al cliente si un pago expira. Ofrece una opción clara para crear una nueva solicitud de pago con un clic.

### 4. Nunca confíes solo en el estado

Verifica siempre que el campo amount coincida con tu monto esperado. No cumplas pedidos por pagos underpaid o failed{" "} sin coordinación.

### 5. Almacena datos de solicitud de pago

Mantén un registro en tu base de datos vinculando:

## Patrones de integración comunes ### Flujo de checkout de e-commerce ```mermaid sequenceDiagram participant C as Customer participant S as Your Store participant F as Fluxis C->>S: Place Order S->>S: Create Order Record S->>F: Create Payment Request F-->>S: Payment Details S->>C: Show Payment QR loop Monitor C->>F: Send Payment F-->>S: Webhook: Processing S->>C: Update UI: Processing F-->>S: Webhook: Completed S->>C: Update UI: Confirmed end S->>S: Fulfill Order S->>C: Send Confirmation Email ``` ### Terminal punto de venta ```mermaid sequenceDiagram participant C as Customer participant T as Terminal participant F as Fluxis T->>T: Cashier Enters Amount T->>F: Create Payment Request F-->>T: Display QR Code C->>F: Customer Scans & Pays loop Poll T->>F: Check Status F-->>T: Status: Processing T->>T: Show "Processing" end F-->>T: Status: Completed T->>T: Print Receipt T->>C: Transaction Complete ``` ## Solución de problemas ### La solicitud de pago no se crea **Síntomas:** Error al crear solicitud de pago **Causas comunes:** - Token de acceso inválido o expirado - El ID de Punto de Venta no existe o no pertenece a tu organización - Formato UAI inválido - El monto es cero o negativo **Solución:** Verifica tu token de autenticación, ID de Punto de Venta y parámetros de la solicitud. ### El estado no se actualiza **Síntomas:** Estado atascado en `created` a pesar del pago del cliente **Causas comunes:** - Pago enviado a dirección incorrecta - Pago enviado con activo/red incorrectos - Confirmaciones de red insuficientes - Pago del cliente pendiente en la billetera **Solución:** Pide al cliente verificar el hash de transacción. Consulta el explorador blockchain para confirmar el estado de la transacción. ### No se reciben webhooks **Síntomas:** No llegan notificaciones webhook **Causas comunes:** - URL de webhook no públicamente accesible - Firewall bloqueando direcciones IP de Fluxis - Endpoint de webhook devolviendo errores - Problemas de certificado SSL/TLS **Solución:** Llama `POST /v1/account/{accountID}/webhook/{webhookID}/test` para una entrega de muestra firmada. Revisa logs del servidor, verifica SSL y confirma que [verificación de firma](/es/docs/developers/webhook-signature-verification) pasa antes de procesar eventos. ## Probar tu integración Antes de ir a producción, prueba tu integración a fondo: ### Lista de verificación de pruebas - [ ] Crear solicitud de pago con parámetros válidos - [ ] Mostrar token NASPIP como código QR - [ ] Monitorear cambios de estado vía polling - [ ] Manejar estado `completed` correctamente - [ ] Manejar estado `expired` con elegancia - [ ] Probar entrega y parseo de webhook - [ ] Verificar firma de webhook usando secreto de la respuesta de creación - [ ] Probar webhook vía `POST /v1/account/{accountID}/webhook/{webhookID}/test` - [ ] Manejar errores de red y reintentos - [ ] Probar casos límite (`underpaid`, `overpaid`) - [ ] Verificar precisión de montos (decimales) ::::tip **Entorno de pruebas** Contacta al soporte de Fluxis para obtener credenciales API de prueba y activos de red de prueba para pruebas de integración antes de ir a producción. ::::