Integración

Cómo integrar la API de LPP en tu sistema: guía paso a paso

LPP Protocol · 1 de abril, 2026 · 11 min de lectura

LPP Protocol API v1 está diseñada para ser integrable en menos de 30 minutos. En este tutorial cubrimos todo el flujo: obtener tu API key, autenticarte, crear un pago, monitorear su estado y recibir confirmaciones automáticas vía webhook.

Los ejemplos están en Node.js y Python, con curl para pruebas rápidas.

Requisitos previos

Paso 1: Autenticación

LPP usa Bearer tokens en el header Authorization. Todos los endpoints requieren autenticación excepto GET /health.

# Verificar que tu API key funciona curl -X GET https://lpp-gateway.aalvarez351.workers.dev/v1/health \ -H "Authorization: Bearer lpp_sk_your_api_key_here" # Respuesta esperada: {"status":"ok","version":"1.0","node":"PA-01","timestamp":"2026-04-01T10:00:00Z"}
! Nunca expongas tu API key en frontend. Siempre llama a LPP desde tu backend server o Cloudflare Worker. Guarda la key en variables de entorno, no en el código.

Paso 2: Crear un pago

El endpoint principal es POST /v1/payments. Puedes pagar usando handles latam:// o wallet addresses directas.

Node.js

const LPP_API = 'https://lpp-gateway.aalvarez351.workers.dev'; const API_KEY = process.env.LPP_API_KEY; async function crearPago({ from, to, amount, currency, network, memo }) { const res = await fetch(`${LPP_API}/v1/payments`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ from, to, amount, currency, network, memo }) }); if (!res.ok) { const err = await res.json(); throw new Error(`LPP error ${res.status}: ${err.message}`); } return res.json(); } // Uso: const pago = await crearPago({ from: 'miempresa@panama', to: 'proveedor@mexico', amount: 1500, currency: 'USDT', network: 'polygon', memo: 'Pago factura #INV-2026-048' }); console.log(pago); /* { payment_id: "lpp_pay_a1b2c3d4", status: "confirmed", tx_hash: "0x9f3a...b7c8", amount: 1500, currency: "USDT", network: "polygon", from: "miempresa@panama", to: "proveedor@mexico", confirmed_at: "2026-04-01T10:00:03Z", fee: 0.001 } */

Python

import httpx import os LPP_API = "https://lpp-gateway.aalvarez351.workers.dev" API_KEY = os.getenv("LPP_API_KEY") def crear_pago(from_handle, to_handle, amount, currency="USDT", network="polygon", memo=""): headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } payload = { "from": from_handle, "to": to_handle, "amount": amount, "currency": currency, "network": network, "memo": memo } resp = httpx.post(f"{LPP_API}/v1/payments", json=payload, headers=headers) resp.raise_for_status() return resp.json() pago = crear_pago( from_handle="miempresa@panama", to_handle="proveedor@colombia", amount=750, memo="Servicio desarrollo Q1 2026" ) print(pago["payment_id"], pago["status"]) # lpp_pay_x1y2z3 confirmed

Paso 3: Verificar el estado de un pago

# Node.js const verificar = await fetch(`${LPP_API}/v1/payments/lpp_pay_a1b2c3d4`, { headers: { 'Authorization': `Bearer ${API_KEY}` } }); const estado = await verificar.json(); // estado.status: 'pending' | 'confirmed' | 'failed'

Los pagos en Polygon confirman en 1–3 segundos. Los pagos en TRC-20 confirman en 30–60 segundos. Para flujos críticos, usa webhooks en vez de polling.

Paso 4: Configurar webhooks

Los webhooks permiten que LPP notifique a tu servidor cuando un pago se confirma, sin que tengas que hacer polling.

# Registrar webhook endpoint curl -X POST https://lpp-gateway.aalvarez351.workers.dev/v1/webhooks \ -H "Authorization: Bearer $LPP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://tu-server.com/webhooks/lpp", "events": ["payment.confirmed", "payment.failed"], "secret": "tu_webhook_secret_seguro" }'

Handler del webhook (Node.js/Express)

const crypto = require('crypto'); app.post('/webhooks/lpp', express.raw({type: 'application/json'}), (req, res) => { // Verificar firma HMAC const signature = req.headers['x-lpp-signature']; const expected = crypto .createHmac('sha256', process.env.WEBHOOK_SECRET) .update(req.body) .digest('hex'); if (signature !== `sha256=${expected}`) { return res.status(401).json({ error: 'Invalid signature' }); } const event = JSON.parse(req.body); switch (event.type) { case 'payment.confirmed': // Marcar factura como pagada en tu DB await markInvoicePaid(event.data.payment_id, event.data.amount); break; case 'payment.failed': // Notificar al equipo, reintentar si aplica await notifyPaymentFailed(event.data); break; } res.json({ received: true }); });

Endpoints de referencia

GET/v1/health
Status del nodo. No requiere autenticación.
POST/v1/payments
Crear un nuevo pago USDT.
GET/v1/payments/:id
Consultar estado de un pago.
GET/v1/payments
Listar pagos. Params: limit, offset, status, from, to.
GET/v1/handles/:handle
Resolver handle latam:// a wallet address.
POST/v1/webhooks
Registrar endpoint de webhook.
GET/v1/balance
Balance USDT disponible por red.
GET/v1/nodes
Estado de los 6 nodos regionales.

Manejo de errores

CódigoErrorSolución
401UnauthorizedVerificar API key en header Authorization
400invalid_handleEl handle latam:// no existe o está mal formado
400insufficient_balanceBalance USDT insuficiente en la wallet origen
400invalid_networknetwork debe ser 'polygon' o 'trc20'
429rate_limit_exceededPlan Free: 100 req/min. Upgrade a Growth para 1,000 req/min.
503node_unavailableReintentar en 5s. El sistema hace failover automático a nodo secundario.

SDK oficial (beta)

Para Node.js existe un SDK oficial en beta que simplifica la integración:

npm install @lpp-protocol/sdk // Uso import { LPPClient } from '@lpp-protocol/sdk'; const lpp = new LPPClient({ apiKey: process.env.LPP_API_KEY }); const pago = await lpp.payments.create({ from: 'miempresa@panama', to: 'proveedor@brasil', amount: 2000, currency: 'USDT' });
Empieza a integrar LPP gratis
Plan Free: 100 transacciones/mes, acceso completo a API, webhooks incluidos. Sin tarjeta de crédito.
Obtener API key →