@veripay/node

El SDK oficial de VeriPay para Node.js. Cobra en bolívares desde tu ecommerce: crea links de pago, verifica pagos contra los bancos venezolanos y valida webhooks — todo con una API tipada y sin dependencias.

📚 Documentación · 🔑 Genera tu API key · 🌐 itsverypay.com

✨ Características

• 🇻🇪 Multi-banco venezolano — BDV, Banesco, Mercantil, Plaza, Bancamiga, BNC y más, en una sola integración.
• 🔗 Links de pago — genéralos por código con monto, concepto y URL de retorno.
• ✅ Verificación real — consulta si un pago fue confirmado contra el banco, no capturas de pantalla.
• 🪝 Webhooks firmados — verifica la firma HMAC-SHA256 en una línea.
• 🧪 Sandbox integrado — prueba el flujo completo con montos mágicos, sin tocar bancos reales.
• 📘 100% TypeScript — tipos incluidos, autocompletado en todo el SDK.
• 🪶 Cero dependencias — usa el fetch nativo de Node 18+. Ligero y rápido.
• 📦 ESM + CommonJS — funciona con import y con require.

🚀 Instalación

npm install @veripay/node

Requiere Node 18+. Genera tus API keys (vp_test_... / vp_live_...) en Panel → Desarrolladores.

⚡ Quick Start

import VeriPay from "@veripay/node";

const veripay = new VeriPay(process.env.VERIPAY_API_KEY); // vp_live_... o vp_test_...

// 1. Crear un link de pago para la orden
const link = await veripay.paymentLinks.create({
  monto: 1250.5,
  concepto: "Orden #4412",
  returnUrl: "https://mitienda.com/checkout/retorno",
});

console.log(link.url); // → redirige a tu cliente aquí

// 2. Al volver el cliente (o al recibir el webhook), confirma el estado
const pago = await veripay.payments.retrieve(paymentId);
if (pago.verificado) {
  // entrega el pedido 🎉
}

📖 Uso

Links de pago

await veripay.paymentLinks.create({ monto: 500, concepto: "Suscripción" });
await veripay.paymentLinks.retrieve("plink_abc123");
await veripay.paymentLinks.list();

Si omites monto, el cliente lo ingresa al pagar. Otras opciones: gatewayIds (limitar a ciertos bancos) y expiraEn (vencimiento en segundos).

Pagos

// Consultar un pago puntual (fuente de verdad antes de entregar el pedido)
const pago = await veripay.payments.retrieve("pay_xyz789");

// Buscar por los últimos dígitos de la referencia bancaria
const { data } = await veripay.payments.search("004521");

🧪 Sandbox

Con una key vp_test_, los links se pagan simulados según los céntimos del monto:

| Monto | Resultado | | :--- | :--- | | *.01 | ✅ Aprobado | | *.02 | ❌ Rechazado | | *.03 | ⏳ Pendiente |

Ningún banco real se ve afectado.

const veripay = new VeriPay("vp_test_...");
veripay.isTestMode; // → true

🪝 Webhooks

Verifica la firma antes de confiar en el evento. Usa el cuerpo crudo del request, no el objeto ya parseado.

import express from "express";
import { constructWebhookEvent } from "@veripay/node";

app.post("/webhooks/veripay", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = constructWebhookEvent(
      req.body.toString(),
      req.header("x-veripay-signature"),
      process.env.VERIPAY_WEBHOOK_SECRET,
    );

    if (event.event === "payment.verified") {
      // marca la orden como pagada ✅
    }
    res.sendStatus(200);
  } catch {
    res.sendStatus(400); // firma inválida
  }
});

🛡️ Manejo de errores

Todas las llamadas lanzan VeriPayError con code y status:

import { VeriPayError } from "@veripay/node";

try {
  await veripay.payments.retrieve("pay_inexistente");
} catch (e) {
  if (e instanceof VeriPayError) {
    console.error(e.code, e.status, e.message); // → payment_not_found 404 ...
  }
}

⚙️ Opciones

new VeriPay(apiKey, {
  baseUrl: "https://dirs-verypay-web.lunsoy.easypanel.host", // por defecto (dominio actual)
  timeout: 15000,                                            // ms por request
});

📚 API

| Método | Descripción | | :--- | :--- | | paymentLinks.create(params) | Crea un link de pago | | paymentLinks.retrieve(id) | Consulta un link | | paymentLinks.list() | Lista tus links | | payments.retrieve(id) | Consulta el estado de un pago | | payments.search(reference) | Busca pagos por referencia | | webhooks.constructEvent(body, sig, secret) | Verifica la firma y devuelve el evento | | webhooks.verifySignature(body, sig, secret) | Solo verifica la firma (boolean) |

Referencia completa y diagramas de integración en la documentación.

📄 Licencia

MIT © VeriPay