Copy page

Tutoriales

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:

Code
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:

Puedes crear tu primera solicitud de pago en nuestro API Playground - 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:

Code
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

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

Code
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

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.

Estrategia de polling

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.

Configuración de webhook

Registra una URL HTTPS completa y establece event_type en payment_request:

Code
{
  "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 y Verificación de firma de webhook. 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

2. Muestra información de pago clara

3. Maneja la expiración con elegancia

4. Nunca confíes solo en el estado

5. Almacena datos de solicitud de pago

Patrones de integración comunes

Flujo de checkout de e-commerce

Code
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

Code
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 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)