Tutoriales

Guía de integración API

Esta guía describe los pasos recomendados para integrarte con la API de Fluxis, desde el aprovisionamiento de credenciales hasta la conciliación de transacciones.

Resumen de la integración

Una integración típica con Fluxis sigue estos pasos:

Aprovisionamiento de credenciales — Crear una clave API en el dashboard (roles read + write)
Autenticación — Intercambiar credenciales por un token de acceso Bearer
Descubrimiento de recursos — Recuperar tus cuentas predeterminadas y puntos de venta predeterminados (los creados al registrarte)
Crear tu POS online — Configurar tu POS para pagos online, para que pueda generar múltiples solicitudes de pago en paralelo
Configuración de liquidación — Configurar la dirección cripto donde se entregarán los activos cobrados. Puedes hacerlo en el dashboard o vía API.
Creación de solicitudes de pago — Crear una solicitud de pago por cada intento de checkout
Monitorear estado de pagos — Webhooks (push) o polling (pull) — elige uno o ambos
Conciliación — Consultar transacciones periódicamente para detectar eventos perdidos

Antes de empezar

Entornos

Entorno	Host
Staging	`https://api.stgfluxis.us`
Production	`https://api.fluxis.us`

Las credenciales de producción se generarán después de que tu integración en staging esté completa y aprobada por Fluxis.

Encabezados requeridos

Todos los endpoints protegidos de Fluxis requieren ambos encabezados:

Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>

Trata tu API Secret como credencial sensible. Nunca lo expongas en código del lado del cliente, navegadores o apps móviles.

Paso 1 — Aprovisionamiento de credenciales

Antes de hacer llamadas API, crea credenciales API en el Dashboard de Fluxis.

¿Nuevo en Fluxis? Completa el Registro de comercio (creación de cuenta + 2FA) antes de este paso.

Crear una clave API en el dashboard

Inicia sesión en el Dashboard de Fluxis (staging o production).
Abre Developers → API Keys (o navega a /app/api-keys).
Haz clic en Create (o equivalente) para agregar una nueva clave.
Asigna los roles read y write para listar recursos y crear solicitudes de pago.
Completa el desafío 2FA cuando se solicite (Autenticación de dos factores debe estar registrada primero).
Copia el API Secret de inmediato — se muestra una vez y no puede recuperarse después.

Recibirás:

API Key ID (p. ej. fxs.stg.<uuid> para staging, fxs.prd.<uuid> para production)
API Secret — guarda en un gestor de secretos o variables de entorno

Consulta Credenciales API para roles, lista blanca de IP y ciclo de vida.

Si operas varias marcas o regiones, coordina con Fluxis temprano para alinear tu estructura de Accounts y Points of Sale. Esto simplificará informes y conciliación.

Paso 2 — Autenticación

Intercambia tus credenciales por un token de acceso que debe incluirse en todas las solicitudes API posteriores.

Endpoint: POST /v1/auth/token

Consulta el formato completo de solicitud/respuesta en nuestra Referencia API - Authentication.

Uso del token

Incluye el token de acceso en todas las solicitudes protegidas:

Code
Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>

Ciclo de vida del token

Expiración: Los tokens de acceso expiran (consulta el campo expired_at en la respuesta)
Renovación: Implementa un mecanismo para renovar el token antes de que expire
Rotación: Rota tu API Key/Secret de inmediato si sospechas que han sido comprometidos

Paso 3 — Descubrimiento de recursos

Después de autenticarte, recupera información sobre tus cuentas y puntos de venta predeterminados, o puedes crear nuevos.

3.1 Recuperar cuentas

Las cuentas representan las cuentas financieras de tu comercio dentro de Fluxis.

Endpoint: GET /v1/account

Consulta el formato completo de respuesta en nuestra Referencia API - Accounts.

3.2 Recuperar puntos de venta

Los Puntos de Venta (POS) representan tus puntos de entrada de pago — ubicaciones físicas o virtuales donde aceptas pagos. Necesitarás el ID del POS al crear solicitudes de pago.

Endpoint: GET /v1/pos?page=1&page_size=20

Parámetros de consulta requeridos: page (≥ 1) y page_size (1–100). Las claves de organización pueden filtrar con account_id.

Consulta el formato completo de respuesta en nuestra Referencia API — Point of Sale.

Más sobre el concepto POS: Punto de Venta.

Paso 4 — Configuración de liquidación

Antes de aceptar pagos, debes configurar adónde se entregarán los activos cripto cobrados.

Todos los activos cobrados de una red específica (p. ej., USDT, USDC u otros tokens en Polygon) se entregarán a la dirección de liquidación configurada para esa red.

Por razones de seguridad, la configuración de direcciones de liquidación actualmente la gestiona manualmente el equipo de Fluxis. Contacta a tu representante de Fluxis para configurar tus direcciones de liquidación en staging y production.

Paso 5 — Creación de solicitudes de pago

Crea una solicitud de pago por cada intento de checkout del cliente. La respuesta incluye un token NASPIP con toda la información de pago.

Endpoint: POST /v1/pos/:posID/payment-request

Campos clave:

amount — El monto del pago (p. ej., "49.99")
unique_asset_id — El activo/red objetivo (más sobre UAIs)
reference_id — Tu ID de pedido interno para conciliación
order — Datos estructurados opcionales del pedido para recibos/UX

Consulta el formato completo de solicitud/respuesta en nuestra Referencia API - Payment Request.

5.1 Mostrar el token NASPIP

El token devuelto en la respuesta es un token NASPIP que presentas al cliente.

Checkout en escritorio: Muestra el token NASPIP como código QR para que los usuarios lo escaneen con su app de billetera.

Checkout móvil: Muestra un botón "Pagar con [nombre de app de billetera]" que abre la app vía deep link:

Code
[wallet app deeplink url]?<custom_query_params>&naspip_token=<NASPIP_TOKEN>

Más sobre NASPIP: Token NASPIP.

Para una lista mantenida de apps de billetera, plantillas de deep link y logos, consulta Registro de apps compatibles.

5.2 Hosted checkout (opcional)

Para una página de pago alojada por Fluxis en lugar de incrustar el token NASPIP tú mismo:

Endpoint: POST /v1/pos/:posID/payment-request-checkout

La respuesta incluye tanto un token como una checkout_url a la que puedes redirigir clientes directamente. La página hosted consulta GET /public/checkout/:sessionId y, al terminar, usa return_url: en un punto de venta genérico es config.return_url del POS; en una sesión Tiendanube es el callback por intento (success, failure o cancel) guardado en Process Payment, no la URL del POS.

Consulta API Reference — Create payment request checkout.

Paso 6 — Elegir cómo monitorear pagos

Después de crear una solicitud de pago, necesitas saber cuándo el cliente paga. Elige una o ambas estrategias:

Estrategia	Entrega	Ideal para	Requisitos
Webhooks (Opción A)	Push — Fluxis hace POST a tu servidor	Integraciones de producción, UX en tiempo real	Endpoint HTTPS público, verificación de firma
Polling (Opción B)	Pull — tu servidor consulta Fluxis	Backends simples, desarrollo local, sin URL pública	Token Bearer + API key válidos; polling cada ~3 segundos

Muchos equipos usan webhooks como principal y polling como respaldo cuando se pierde un webhook o tu endpoint estuvo temporalmente caído.

Opción A — Notificaciones webhook

Los webhooks son la forma recomendada de recibir actualizaciones de estado de pago en tiempo real.

A.1 Configurar tu endpoint webhook

Primero, asegúrate de tener un endpoint HTTPS públicamente accesible listo para recibir solicitudes POST de Fluxis.

Luego registra un webhook en la cuenta vinculada a tu POS (usa el account_id de tu POS o lista de cuentas):

Endpoint: POST /v1/account/{accountID}/webhook


Code
{
  "url": "https://your-server.com/webhooks/fluxis",
  "event_type": "payment_request"
}

Fluxis devuelve un secret una vez al crear — guárdalo de forma segura para verificación de firma.

Consulta API Reference — Create webhook.

A.2 Eventos webhook

Fluxis envía webhooks payment_request cuando el estado se vuelve:

Estado	Descripción	Webhook entregado
`processing`	Pago detectado, esperando confirmaciones blockchain	Sí
`completed`	Pago confirmado — cumple el pedido	Sí
`underpaid`	El cliente envió menos del monto solicitado	Sí
`overpaid`	El cliente envió más del monto solicitado	Sí
`expired`	Sin pago a tiempo	No — usa polling
`failed`	Error inesperado de procesamiento	No — polling / soporte

Los estados underpaid y overpaid son casos límite que pueden implicar una configuración incorrecta del lado de la app de billetera, ya que los tokens NASPIP ya contienen el monto esperado. Para pasos de verificación de firma, consulta Verificación de firma de webhook.

A.3 Manejar webhooks

Cuando recibes una notificación webhook:

Verificar autenticidad — Valida la firma HMAC sobre el cuerpo parseado completo { "data": … } usando el secreto de la creación — consulta Verificación de firma de webhook
Procesar el estado — Actualiza el estado interno del pedido y notifica al cliente
Confirmar recepción — Devuelve HTTP 200 OK para confirmar recepción

Tu endpoint debe responder rápido (< 2 segundos). Encola cualquier procesamiento pesado para ejecución en segundo plano. No confirmar puede hacer que Fluxis reenvíe la notificación.

A.4 Idempotencia

Puedes recibir eventos webhook duplicados. Asegúrate de que tu manejador sea idempotente — procesar el mismo evento varias veces debe producir el mismo resultado.

A.5 Probar tu manejador

Después del registro, dispara una entrega de muestra firmada:

Endpoint: POST /v1/account/{accountID}/webhook/{webhookID}/test

Fluxis hace POST de un payload payment_request_status_update usando la misma ruta de firma que producción. Verifica la firma en tu manejador y devuelve HTTP 200. Consulta Verificación de firma de webhook para las reglas de JSON canónico y el ejemplo trabajado.

También puedes registrar webhooks desde el dashboard en Developers → Webhooks. Consulta Webhooks para opciones API y dashboard.

Opción B — Polling

Si no tienes un endpoint HTTPS público — o prefieres una primera integración más simple — haz polling del estado de la solicitud de pago en un intervalo fijo (por ejemplo, cada 3 segundos) hasta que el estado sea terminal.

Endpoint: GET /v1/pos/:posID/payment-request/:paymentRequestID

Encabezados requeridos: Authorization: Bearer <token> y x-fluxis-api-key: <your_api_key>.

Patrón de polling recomendado

Después de crear una solicitud de pago, registra paymentRequestID y posID.
Haz polling cada ~3 segundos mientras el estado sea created, pending, confirmed o processing.
Detén el polling cuando el estado sea terminal: completed, expired, underpaid, overpaid o failed.
En completed, cumple el pedido; en expired, ofrece crear una nueva solicitud.

Las solicitudes de pago expiran después de unos 8 minutos. Evita hacer polling más rápido que una vez por segundo — 3 segundos es un valor razonable para UX de checkout.

Ejemplo (curl):

Code
curl "https://api.stgfluxis.us/v1/pos/${POS_ID}/payment-request/${PAYMENT_REQUEST_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-fluxis-api-key: ${API_KEY}"

Ejemplo (bucle Node.js):


Code
const TERMINAL = new Set([
  "completed",
  "expired",
  "underpaid",
  "overpaid",
  "failed",
]);
const POLL_MS = 3000;

async function waitForPayment(posId, paymentRequestId) {
  while (true) {
    const res = await fetch(
      `${API_BASE}/v1/pos/${posId}/payment-request/${paymentRequestId}`,
      {
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "x-fluxis-api-key": apiKey,
        },
      },
    );
    const { data } = await res.json();
    if (TERMINAL.has(data.status)) return data;
    await new Promise((r) => setTimeout(r, POLL_MS));
  }
}

Consulta el formato completo de respuesta en nuestra Referencia API — Get payment request.

Los estados expired y failed no disparan webhooks — se requiere polling (o comprobaciones manuales) para esos resultados.

Paso 7 — Conciliación

Incluso con webhooks o polling en el momento del checkout, ejecuta conciliación periódica para asegurar que no se perdieron pagos (tiempo de inactividad, problemas de red o bugs del manejador).

Consultar una solicitud de pago específica

Si no recibiste un webhook (o tu sistema estuvo caído), obtén el estado de la solicitud de pago directamente:

Endpoint: GET /v1/pos/:posID/payment-request/:paymentRequestID

Listar transacciones para conciliación

Para conciliación por lotes, consulta el endpoint de transacciones:

Endpoint: GET /v1/transactions?page=1&page_size=50

Parámetros de consulta requeridos: page (≥ 1) y page_size (5–100).

Filtros opcionales:

accountID — Filtrar por cuenta (solo claves API a nivel de organización)

La respuesta está paginada: { data, total, page, page_size, total_pages }.

Un patrón de conciliación común: listar periódicamente transacciones completed y emparejarlas con tus pedidos internos por ID de referencia, monto y marca de tiempo.

Ciclo de vida de solicitud de pago

Las solicitudes de pago pasan por los siguientes estados:

Estado	Descripción	Acción del comercio
`pending`	Checkout creado, moneda no seleccionada	Esperar o mostrar hosted checkout
`created`	Dirección asignada, esperando pago	Mostrar QR/enlace al cliente
`confirmed`	Paso de confirmación interna	Normalmente sin acción del comercio
`processing`	Pago detectado, esperando confirmaciones	Seguir esperando — no cumplir aún
`completed`	Pago confirmado	Cumplir el pedido
`expired`	Sin pago recibido a tiempo	Ofrecer al cliente reintentar (crear nueva solicitud)
`underpaid` / `overpaid` / `failed`	Casos límite	Contactar soporte de Fluxis

Más información: Flujos de pago - Camino feliz y Flujos de pago - Casos límite.

Lista de verificación para producción

Antes de ir a producción, verifica:

¿Necesitas ayuda?

Si tienes preguntas sobre incorporación, credenciales o preparación para producción, contáctanos en [email protected].

Last modified on October 12, 2026

Aceptar pagos desde el Dashboard Crear y monitorear solicitudes de pago

Tutoriales

Guía de integración API

Esta guía describe los pasos recomendados para integrarte con la API de Fluxis, desde el aprovisionamiento de credenciales hasta la conciliación de transacciones.

Resumen de la integración

Una integración típica con Fluxis sigue estos pasos:

Aprovisionamiento de credenciales — Crear una clave API en el dashboard (roles read + write)
Autenticación — Intercambiar credenciales por un token de acceso Bearer
Descubrimiento de recursos — Recuperar tus cuentas predeterminadas y puntos de venta predeterminados (los creados al registrarte)
Crear tu POS online — Configurar tu POS para pagos online, para que pueda generar múltiples solicitudes de pago en paralelo
Configuración de liquidación — Configurar la dirección cripto donde se entregarán los activos cobrados. Puedes hacerlo en el dashboard o vía API.
Creación de solicitudes de pago — Crear una solicitud de pago por cada intento de checkout
Monitorear estado de pagos — Webhooks (push) o polling (pull) — elige uno o ambos
Conciliación — Consultar transacciones periódicamente para detectar eventos perdidos

Antes de empezar

Entornos

Entorno	Host
Staging	`https://api.stgfluxis.us`
Production	`https://api.fluxis.us`

Las credenciales de producción se generarán después de que tu integración en staging esté completa y aprobada por Fluxis.

Encabezados requeridos

Todos los endpoints protegidos de Fluxis requieren ambos encabezados:

Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>

Trata tu API Secret como credencial sensible. Nunca lo expongas en código del lado del cliente, navegadores o apps móviles.

Paso 1 — Aprovisionamiento de credenciales

Antes de hacer llamadas API, crea credenciales API en el Dashboard de Fluxis.

¿Nuevo en Fluxis? Completa el Registro de comercio (creación de cuenta + 2FA) antes de este paso.

Crear una clave API en el dashboard

Inicia sesión en el Dashboard de Fluxis (staging o production).
Abre Developers → API Keys (o navega a /app/api-keys).
Haz clic en Create (o equivalente) para agregar una nueva clave.
Asigna los roles read y write para listar recursos y crear solicitudes de pago.
Completa el desafío 2FA cuando se solicite (Autenticación de dos factores debe estar registrada primero).
Copia el API Secret de inmediato — se muestra una vez y no puede recuperarse después.

Recibirás:

API Key ID (p. ej. fxs.stg.<uuid> para staging, fxs.prd.<uuid> para production)
API Secret — guarda en un gestor de secretos o variables de entorno

Consulta Credenciales API para roles, lista blanca de IP y ciclo de vida.

Si operas varias marcas o regiones, coordina con Fluxis temprano para alinear tu estructura de Accounts y Points of Sale. Esto simplificará informes y conciliación.

Paso 2 — Autenticación

Intercambia tus credenciales por un token de acceso que debe incluirse en todas las solicitudes API posteriores.

Endpoint: POST /v1/auth/token

Consulta el formato completo de solicitud/respuesta en nuestra Referencia API - Authentication.

Uso del token

Incluye el token de acceso en todas las solicitudes protegidas:

Code
Authorization: Bearer <access_token>
x-fluxis-api-key: <your_api_key>

Ciclo de vida del token

Expiración: Los tokens de acceso expiran (consulta el campo expired_at en la respuesta)
Renovación: Implementa un mecanismo para renovar el token antes de que expire
Rotación: Rota tu API Key/Secret de inmediato si sospechas que han sido comprometidos

Paso 3 — Descubrimiento de recursos

Después de autenticarte, recupera información sobre tus cuentas y puntos de venta predeterminados, o puedes crear nuevos.

3.1 Recuperar cuentas

Las cuentas representan las cuentas financieras de tu comercio dentro de Fluxis.

Endpoint: GET /v1/account

Consulta el formato completo de respuesta en nuestra Referencia API - Accounts.

3.2 Recuperar puntos de venta

Los Puntos de Venta (POS) representan tus puntos de entrada de pago — ubicaciones físicas o virtuales donde aceptas pagos. Necesitarás el ID del POS al crear solicitudes de pago.

Endpoint: GET /v1/pos?page=1&page_size=20

Parámetros de consulta requeridos: page (≥ 1) y page_size (1–100). Las claves de organización pueden filtrar con account_id.

Consulta el formato completo de respuesta en nuestra Referencia API — Point of Sale.

Más sobre el concepto POS: Punto de Venta.

Paso 4 — Configuración de liquidación

Antes de aceptar pagos, debes configurar adónde se entregarán los activos cripto cobrados.

Todos los activos cobrados de una red específica (p. ej., USDT, USDC u otros tokens en Polygon) se entregarán a la dirección de liquidación configurada para esa red.

Paso 5 — Creación de solicitudes de pago

Crea una solicitud de pago por cada intento de checkout del cliente. La respuesta incluye un token NASPIP con toda la información de pago.

Endpoint: POST /v1/pos/:posID/payment-request

Campos clave:

amount — El monto del pago (p. ej., "49.99")
unique_asset_id — El activo/red objetivo (más sobre UAIs)
reference_id — Tu ID de pedido interno para conciliación
order — Datos estructurados opcionales del pedido para recibos/UX

Consulta el formato completo de solicitud/respuesta en nuestra Referencia API - Payment Request.

5.1 Mostrar el token NASPIP

El token devuelto en la respuesta es un token NASPIP que presentas al cliente.

Checkout en escritorio: Muestra el token NASPIP como código QR para que los usuarios lo escaneen con su app de billetera.

Checkout móvil: Muestra un botón "Pagar con [nombre de app de billetera]" que abre la app vía deep link:

Code
[wallet app deeplink url]?<custom_query_params>&naspip_token=<NASPIP_TOKEN>

Más sobre NASPIP: Token NASPIP.

Para una lista mantenida de apps de billetera, plantillas de deep link y logos, consulta Registro de apps compatibles.

5.2 Hosted checkout (opcional)

Para una página de pago alojada por Fluxis en lugar de incrustar el token NASPIP tú mismo:

Endpoint: POST /v1/pos/:posID/payment-request-checkout

Consulta API Reference — Create payment request checkout.

Paso 6 — Elegir cómo monitorear pagos

Después de crear una solicitud de pago, necesitas saber cuándo el cliente paga. Elige una o ambas estrategias:

Estrategia	Entrega	Ideal para	Requisitos
Webhooks (Opción A)	Push — Fluxis hace POST a tu servidor	Integraciones de producción, UX en tiempo real	Endpoint HTTPS público, verificación de firma
Polling (Opción B)	Pull — tu servidor consulta Fluxis	Backends simples, desarrollo local, sin URL pública	Token Bearer + API key válidos; polling cada ~3 segundos

Muchos equipos usan webhooks como principal y polling como respaldo cuando se pierde un webhook o tu endpoint estuvo temporalmente caído.

Opción A — Notificaciones webhook

Los webhooks son la forma recomendada de recibir actualizaciones de estado de pago en tiempo real.

A.1 Configurar tu endpoint webhook

Primero, asegúrate de tener un endpoint HTTPS públicamente accesible listo para recibir solicitudes POST de Fluxis.

Luego registra un webhook en la cuenta vinculada a tu POS (usa el account_id de tu POS o lista de cuentas):

Endpoint: POST /v1/account/{accountID}/webhook


Code
{
  "url": "https://your-server.com/webhooks/fluxis",
  "event_type": "payment_request"
}

Fluxis devuelve un secret una vez al crear — guárdalo de forma segura para verificación de firma.

Consulta API Reference — Create webhook.

A.2 Eventos webhook

Fluxis envía webhooks payment_request cuando el estado se vuelve:

Estado	Descripción	Webhook entregado
`processing`	Pago detectado, esperando confirmaciones blockchain	Sí
`completed`	Pago confirmado — cumple el pedido	Sí
`underpaid`	El cliente envió menos del monto solicitado	Sí
`overpaid`	El cliente envió más del monto solicitado	Sí
`expired`	Sin pago a tiempo	No — usa polling
`failed`	Error inesperado de procesamiento	No — polling / soporte

A.3 Manejar webhooks

Cuando recibes una notificación webhook:

Verificar autenticidad — Valida la firma HMAC sobre el cuerpo parseado completo { "data": … } usando el secreto de la creación — consulta Verificación de firma de webhook
Procesar el estado — Actualiza el estado interno del pedido y notifica al cliente
Confirmar recepción — Devuelve HTTP 200 OK para confirmar recepción

Tu endpoint debe responder rápido (< 2 segundos). Encola cualquier procesamiento pesado para ejecución en segundo plano. No confirmar puede hacer que Fluxis reenvíe la notificación.

A.4 Idempotencia

Puedes recibir eventos webhook duplicados. Asegúrate de que tu manejador sea idempotente — procesar el mismo evento varias veces debe producir el mismo resultado.

A.5 Probar tu manejador

Después del registro, dispara una entrega de muestra firmada:

Endpoint: POST /v1/account/{accountID}/webhook/{webhookID}/test

También puedes registrar webhooks desde el dashboard en Developers → Webhooks. Consulta Webhooks para opciones API y dashboard.

Opción B — Polling

Endpoint: GET /v1/pos/:posID/payment-request/:paymentRequestID

Encabezados requeridos: Authorization: Bearer <token> y x-fluxis-api-key: <your_api_key>.

Patrón de polling recomendado

Después de crear una solicitud de pago, registra paymentRequestID y posID.
Haz polling cada ~3 segundos mientras el estado sea created, pending, confirmed o processing.
Detén el polling cuando el estado sea terminal: completed, expired, underpaid, overpaid o failed.
En completed, cumple el pedido; en expired, ofrece crear una nueva solicitud.

Las solicitudes de pago expiran después de unos 8 minutos. Evita hacer polling más rápido que una vez por segundo — 3 segundos es un valor razonable para UX de checkout.

Ejemplo (curl):

Code
curl "https://api.stgfluxis.us/v1/pos/${POS_ID}/payment-request/${PAYMENT_REQUEST_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-fluxis-api-key: ${API_KEY}"

Ejemplo (bucle Node.js):


Code
const TERMINAL = new Set([
  "completed",
  "expired",
  "underpaid",
  "overpaid",
  "failed",
]);
const POLL_MS = 3000;

async function waitForPayment(posId, paymentRequestId) {
  while (true) {
    const res = await fetch(
      `${API_BASE}/v1/pos/${posId}/payment-request/${paymentRequestId}`,
      {
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "x-fluxis-api-key": apiKey,
        },
      },
    );
    const { data } = await res.json();
    if (TERMINAL.has(data.status)) return data;
    await new Promise((r) => setTimeout(r, POLL_MS));
  }
}

Consulta el formato completo de respuesta en nuestra Referencia API — Get payment request.

Los estados expired y failed no disparan webhooks — se requiere polling (o comprobaciones manuales) para esos resultados.

Paso 7 — Conciliación

Incluso con webhooks o polling en el momento del checkout, ejecuta conciliación periódica para asegurar que no se perdieron pagos (tiempo de inactividad, problemas de red o bugs del manejador).

Consultar una solicitud de pago específica

Si no recibiste un webhook (o tu sistema estuvo caído), obtén el estado de la solicitud de pago directamente:

Endpoint: GET /v1/pos/:posID/payment-request/:paymentRequestID

Listar transacciones para conciliación

Para conciliación por lotes, consulta el endpoint de transacciones:

Endpoint: GET /v1/transactions?page=1&page_size=50

Parámetros de consulta requeridos: page (≥ 1) y page_size (5–100).

Filtros opcionales:

accountID — Filtrar por cuenta (solo claves API a nivel de organización)

La respuesta está paginada: { data, total, page, page_size, total_pages }.

Un patrón de conciliación común: listar periódicamente transacciones completed y emparejarlas con tus pedidos internos por ID de referencia, monto y marca de tiempo.

Ciclo de vida de solicitud de pago

Las solicitudes de pago pasan por los siguientes estados:

Estado	Descripción	Acción del comercio
`pending`	Checkout creado, moneda no seleccionada	Esperar o mostrar hosted checkout
`created`	Dirección asignada, esperando pago	Mostrar QR/enlace al cliente
`confirmed`	Paso de confirmación interna	Normalmente sin acción del comercio
`processing`	Pago detectado, esperando confirmaciones	Seguir esperando — no cumplir aún
`completed`	Pago confirmado	Cumplir el pedido
`expired`	Sin pago recibido a tiempo	Ofrecer al cliente reintentar (crear nueva solicitud)
`underpaid` / `overpaid` / `failed`	Casos límite	Contactar soporte de Fluxis

Más información: Flujos de pago - Camino feliz y Flujos de pago - Casos límite.

Lista de verificación para producción

Antes de ir a producción, verifica:

¿Necesitas ayuda?

Si tienes preguntas sobre incorporación, credenciales o preparación para producción, contáctanos en [email protected].

Last modified on October 12, 2026

Aceptar pagos desde el Dashboard Crear y monitorear solicitudes de pago