Biblioteca para Node.js / TypeScript
Acepta pagos en cripto en tu app de Node.js
Crea una factura en cripto desde tu servidor Node.js, envía al cliente a la página de pago de ArionPay y verifica el webhook firmado cuando pague. El dinero va directo a tu propia billetera.
Instalar
npm install arionpayQué hace
ArionPay para desarrolladores de Node.js
Leer más
No tiene dependencias, incluye builds ESM y CommonJS con tipos de TypeScript y funciona en Node.js 18 o posterior. ArionPay nunca custodia el dinero: cada pago va directamente a tu propia billetera.- Sin dependencias. Node.js 18 o posterior.
- ESM y CommonJS, con tipos de TypeScript.
- Cada solicitud de factura lleva una clave de idempotencia, así que un error de red nunca puede crear dos facturas. Hasta 3 intentos de forma predeterminada (maxAttempts).
- Firma cada solicitud de factura con HMAC-SHA256 y tu secreto de API. El secreto en sí nunca se envía.
- verifyWebhook comprueba el encabezado ArionPay-Signature sobre el cuerpo sin procesar y lanza ArionPaySignatureError cuando no coincide o tiene más de 5 minutos.
- simulatePayment lleva una factura de prueba por escenarios como exact, underpaid_1pct, overpaid o late, y sendTestWebhook envía un evento de ejemplo firmado.
- Los errores son ArionPayError, con un estado HTTP y un código como rate_limited o unknown_asset. Los mensajes nunca contienen tu secreto.
Requisitos y licencia
- Funciona con
- Node.js 18 o posterior · Express, Next.js (App Router) · ESM, CommonJS y tipos de TypeScript
- Precio
- La biblioteca es gratuita. ArionPay cobra un 0.5% por pago, sin cuota mensual.
- Código fuente
- Código abierto (MIT) en GitHub.
Configuración
Configúralo en 5 pasos
Paso 1
Instala el paquete
Ejecuta npm install arionpay. No tiene dependencias.
Paso 2
Copia tus claves
En tu panel de ArionPay, abre tu tienda y copia la clave de API (pk_) y el secreto de API (sk_; te pide tu código de autenticación). El secreto de firma del webhook (whsec_) está en la página Webhooks. Guarda los tres en tu servidor, nunca en código del navegador.
Paso 3
Crear una factura
Llama a createInvoice con el importe, la moneda y tu orderId, y luego redirige al cliente a invoice.invoiceUrl.
Paso 4
Verifica el webhook
Configura la dirección de tu webhook en la página Webhooks, o por factura con callbackUrl. Lee el cuerpo con express.raw, pásalo a verifyWebhook y entrega el pedido con invoice.paid.
Paso 5
Prueba sin dinero real
Crea una factura con test: true y un asset como USDT_TRC20, y luego llama a simulatePayment(invoice.id, "exact"). Tu webhook recibe invoice.paid, como con un pago real.
Después de la configuración
Cómo llega un pago a tu código
- invoice.pending: se detectó un pago en la red y espera confirmaciones. Muestra "pago en camino", pero no entregues todavía.
- invoice.paid: pagada por completo y confirmada, o aceptada por ti a mano en el panel. Entrega el pedido solo con este evento (o cuando getInvoice indique paid). Que un cliente vuelva a successUrl no demuestra nada.
- Antes de entregar, comprueba que la factura corresponde a tu pedido: tu orderId o metadata, y el mismo importe y la misma moneda que el total actual del pedido.
- invoice.partial, invoice.expired e invoice.needs_review nunca significan que debas entregar. Un pago tardío todavía puede convertir una factura vencida en pagada.
- ArionPay reenvía un webhook durante unos 3 días hasta que tu servidor responde 2xx, así que el mismo evento puede llegar dos veces. Usa event.id para procesar cada uno una sola vez.
16 monedas y tokens en 9 redes
Todas las monedas- BTCBitcoin
- ETHEthereum
- USDTEthereum
- USDCEthereum
- BNBBNB Smart Chain
- USDTBNB Smart Chain
- USDCBNB Smart Chain
- POLPolygon
- USDTPolygon
- USDCPolygon
- TRXTRON
- USDTTRON
- LTCLitecoin
- DOGEDogecoin
- BCHBitcoin Cash
- DASHDash
Preguntas sobre la biblioteca de ArionPay para Node.js
Respuestas breves antes de empezar a programar.