Copy page

Token NASPIP

Especificación del protocolo

Este documento proporciona la especificación técnica del Network-Agnostic Secure Payment Instruction Protocol (NASPIP) tal como lo implementan Fluxis y naspip-go.

Descripción general

NASPIP define un formato estandarizado para instrucciones de pago que pueden transmitirse y validarse de forma segura en cualquier red de pago. Los tokens son PASETO v4 public (firmados, no cifrados) — cualquiera con la clave pública del emisor puede verificar autenticidad e integridad del payload.

Estructura de datos

Formato del token NASPIP

Un token NASPIP es una cadena delimitada por punto y coma que envuelve un token PASETO v4 public:

Code
naspip;{key_issuer};{key_id};v4.public.{paseto_token}

Component	Description	Example
Prefix	Identificador del protocolo	naspip
Key issuer (kis)	Entidad que emitió la clave de firma	fluxis.us
Key ID (kid)	Identificador de la clave de firma	fluxis.qr.dyn.1
PASETO token	Token PASETO v4 public que contiene el payload firmado	v4.public.IhYyMDI...

El payload interno de PASETO usa claims estándar (iss, sub, exp, iat, kid, kis, kep) más un campo data que contiene instrucciones de pago o un payload URL.

Esquemas de payload

NASPIP admite dos tipos de payload dentro del campo data del token PASETO.

Payload de instrucción (pago directo)

Code
{
  "payment": {
    "id": "180ede28-2968-4ac7-8e81-ca446f201949",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "unique_asset_id": "npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "is_open": false,
    "amount": "49.99",
    "expires_at": 1759397652
  },
  "order": {
    "total": "49.99",
    "coin_code": "USD",
    "description": "Order description",
    "merchant": {
      "name": "Merchant #1",
      "description": "Merchant description"
    },
    "items": []
  }
}

Payload URL (checkout / instrucciones diferidas)

Code
{
  "url": "https://api.fluxis.us/v1/pos/{posID}/payment-request-checkout",
  "payment_options": ["npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"],
  "order": {
    "total": "49.99",
    "coin_code": "USD",
    "merchant": { "name": "Merchant #1" }
  }
}

Los códigos QR estáticos de PoS pueden omitir payment_options; las wallets llaman POST /v1/naspip/read y Fluxis resuelve las instrucciones obteniendo la URL cuando payment_options está ausente.

Operaciones criptográficas

NASPIP usa tokens PASETO v4 public con claves Ed25519. Los payloads se codifican en protobuf antes de firmar. En Fluxis, use naspip-go o la REST API — no implemente Ed25519+SHA-256 crudo sobre JSON.

Firma (create)

1. Construir InstructionPayload o UrlPayload
2. Codificar el payload como protobuf
3. Firmar con PASETO v4 usando la clave privada Ed25519 del emisor
4. Prefijar con naspip;{kis};{kid};

TTL predeterminado del token: 1 hora para instrucciones de pago; 10 años (87600h) para payloads solo URL.

Verificación (read)

1. Dividir el token por ; y validar el prefijo naspip
2. Resolver la clave pública por kis + kid
3. Verificar la firma PASETO v4 y los claims de expiración
4. Devolver PasetoCompleteResult con payload.data parseado

Forma de respuesta de Fluxis POST /v1/naspip/read

Code
{
  "status": "success",
  "data": {
    "version": "v4",
    "purpose": "public",
    "footer": null,
    "payload": {
      "iss": "fluxis.us",
      "sub": "naspip",
      "exp": "2026-12-31T23:59:59.000Z",
      "iat": "2026-01-01T00:00:00.000Z",
      "kid": "fluxis.qr.dyn.1",
      "kis": "fluxis.us",
      "data": { "payment": { "...": "..." } }
    }
  }
}

::::warning Discrepancia en Swagger OpenAPI documenta actualmente data como PasetoV4PayloadData plano (url, payment, order). La respuesta en runtime es PasetoCompleteResult como se muestra arriba. Consulte NASPIP_ENHANCEMENTS.md para la corrección planificada. :::::

Soporte de redes

Las instrucciones de pago referencian activos por unique_asset_id (UAI), no por nombre de red o chain ID. Fluxis admite múltiples redes — consulte UAI para la lista completa de activos.

UAIs de ejemplo:

Network	Asset	Example UAI
Polygon	USDC	npolygon_t0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
Base	USDC	nbase_t0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Avalanche	USDC	navalanche_t0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E
Avalanche	ARGt	navalanche_t0x2E4e93eCA2E16E4989b894e188B7F7fC0175703B
Arbitrum	USDC	narbitrum_t0xaf88d065e77c8cC2239327C5EDb3A432268e5831
Arbitrum	USDT	narbitrum_t0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9

Formato de código QR

Los tokens NASPIP se codifican en códigos QR como la cadena de token cruda (no una URI naspip://):

Code
naspip;fluxis.us;fluxis.qr.dyn.1;v4.public.IhYyMDI...

Especificaciones del código QR

• Error Correction: Level M (15% recovery)
• Size: Minimum 256x256 pixels
• Format: Standard QR Code (ISO/IEC 18004)

Versionado

Los tokens NASPIP usan PASETO v4 (v4.public.*). El prefijo delimitador por punto y coma es naspip. Los cambios incompatibles en esquemas de payload se gestionan mediante releases de naspip-go.

Manejo de errores

Códigos de error de la API Fluxis (relacionados con NASPIP)

Code	HTTP	Description
MD0006	406	Token NASPIP expirado
GE0003	404	Clave pública expirada
MD0004	400	Datos inválidos (p. ej. token o URL inválidos)
PR0006	404	No hay solicitud de pago activa (PoS caja; devuelto al resolver payload URL)

Formato de respuesta de error

Code
{
  "status": "error",
  "error": {
    "code": "MD0006",
    "message": "NASPIP token expired"
  }
}

Consideraciones de seguridad

Buenas prácticas

1. Administración de claves: Fluxis gestiona las claves de firma; los integradores verifican vía búsqueda de clave pública (kis + kid)
2. Expiración del token: Los tokens de instrucción de pago expiran tras 1 hora por defecto
3. Validación de importes: Valide importes en el lado del emisor y del receptor
4. Verificación de activos: Confirme que unique_asset_id coincide con la red y token esperados
5. Verificación de firma: Verifique siempre los tokens PASETO antes de procesar pagos

Modelo de amenazas

NASPIP protege contra:

• Manipulación de datos: Las firmas PASETO v4 previenen modificaciones
• Ataques de replay: La expiración del token y el ciclo de vida de la solicitud de pago previenen reutilización
• Suplantación: La verificación de clave pública vía kis + kid garantiza autenticidad

Directrices de implementación

Campos requeridos (payload de instrucción)

• payment.address — dirección de destino
• payment.unique_asset_id — activo objetivo (UAI)
• payment.amount — importe del pago
• payment.is_open — si el importe es abierto

Campos opcionales

• payment.id — identificador de solicitud de pago
• payment.expires_at — expiración timestamp Unix
• order — metadatos de comerciante y pedido

Reglas de validación

1. El token debe parsearse como naspip;{kis};{kid};v4.public.{paseto}
2. La firma PASETO y la expiración deben ser válidas
3. La clave pública para kis + kid no debe estar expirada
4. unique_asset_id debe ser un UAI admitido

Resolución de payload URL (Fluxis)

Cuando POST /v1/naspip/read recibe un token cuyo payload.data contiene una url no vacía y no payment_options:

1. Fluxis realiza un HTTP GET a esa URL
2. En caso de éxito, reemplaza payload.data con las instrucciones de checkout/pago obtenidas
3. En caso de fallo, devuelve MD0004 o PR0006 según corresponda

Si payment_options está presente, el token se devuelve tal cual y la wallet selecciona un activo antes de una llamada de checkout posterior.

Endpoints de la API Fluxis

Endpoint	Method	Auth	Description
/v1/naspip/read	POST	Bearer + x-fluxis-api-key	Verificar token y devolver PasetoCompleteResult
/v1/naspip/create	POST	Bearer + x-fluxis-api-key	Crear token desde payload de instrucción o URL

Consulte la Implementation Guide para ejemplos curl.

Referencias

• NASPIP Protocol (GitHub)
• naspip-go library
• PASETO specification
• ISO/IEC 18004 - QR Code