wolvpay-node

Official Node.js / TypeScript SDK for the WolvPay cryptocurrency payment API.

---

What is WolvPay?

WolvPay is a secure, low-fee cryptocurrency payment processor built for developers and businesses. It lets you accept payments in Bitcoin, Litecoin, USDT, USDC, and many other cryptocurrencies — either through a hosted payment page (zero front-end work) or a fully white-label flow where you control the entire UI.

This is the official Node.js / TypeScript SDK. It wraps the WolvPay REST API so you can create and manage invoices, verify webhook signatures, and handle payment events with fully-typed async/await code. Works in any Node.js backend including Express, Fastify, and Next.js.

API docs: wolvpay.com/docs
Dashboard: wolvpay.com/home
Discord: wolvpay.com/discord

---

Requirements

• Node.js 18 or higher (uses native fetch)
• TypeScript 5.x (optional — works with plain JavaScript too)

---

Installation

npm install @wolvpay/sdk
# or
yarn add @wolvpay/sdk
# or
pnpm add @wolvpay/sdk

---

Quick Start

import { WolvPayClient } from '@wolvpay/sdk';

const client = new WolvPayClient(process.env.WOLVPAY_API_KEY!);

// Create a hosted invoice and redirect the user
const invoice = await client.createInvoice({
  amount: 50,
  currency: 'USD',
  white_label: false,
  redirect_url: 'https://example.com/thank-you',
});

console.log(invoice.url); // https://invoices.wolvpay.com/INV...
// Redirect user to invoice.url

---

Configuration

import { WolvPayClient } from '@wolvpay/sdk';

const client = new WolvPayClient(process.env.WOLVPAY_API_KEY!);

Security: Never expose your API key client-side. Use environment variables.

---

API Reference

Coins

client.getCoins()

Retrieve all supported cryptocurrencies and their current exchange rates.

const coins = await client.getCoins();

for (const coin of coins) {
  console.log(`${coin.name}: $${coin.prices['USD']}`);
}

Returns: Promise<Coin[]>

---

Invoices

client.createInvoice(params)

Create a new payment invoice.

// Hosted invoice — customer pays on WolvPay's page
const invoice = await client.createInvoice({
  amount: 100,
  currency: 'USD',
  description: 'Order #1234',
  white_label: false,
  redirect_url: 'https://example.com/thank-you',
});
// → invoice.url is the hosted payment page

// White-label — show payment details on your own UI
const invoice = await client.createInvoice({
  amount: 100,
  currency: 'EUR',
  coin: 'ltc',
  white_label: true,
});
// → invoice.coin_address and invoice.coin_amount

// Let the customer choose the coin
const invoice = await client.createInvoice({ amount: 100 });
// → invoice.status === 'AWAITING_SELECTION'
// → invoice.available_coins lists supported options

Parameters:

Field	Type	Required	Description
amount	number	Yes	Payment amount.
currency	string	No	Fiat code (default: "USD").
coin	string	No	Crypto code (e.g. "btc", "ltc"). Omit to use AWAITING_SELECTION.
description	string	No	Invoice description.
white_label	boolean	No	true = white-label, false = hosted. Default: true.
redirect_url	string	No	Post-payment redirect URL.

Returns: Promise<Invoice>

---

client.getInvoice(invoiceId)

Retrieve a specific invoice by ID.

const invoice = await client.getInvoice('INVabc123def456');

if (invoice.status === 'AWAITING_PAYMENT') {
  console.log(`Send ${invoice.coin_amount} ${invoice.coin}`);
  console.log(`To: ${invoice.coin_address}`);
}

Returns: Promise<Invoice>

---

client.updateInvoice(invoiceId, coin)

Select a cryptocurrency for a white-label invoice in AWAITING_SELECTION status.

const updated = await client.updateInvoice('INVabc123def456', 'ltc');
console.log(updated.coin_address); // LTC payment address

Returns: Promise<Invoice>

---

client.listInvoices(page?, limit?)

List all invoices with pagination.

const result = await client.listInvoices(1, 3);

for (const invoice of result.invoices) {
  console.log(invoice.invoice_id, invoice.status);
}

console.log(result.pagination.total_items);

Returns: Promise<InvoiceList>

---

Webhooks

WolvPay sends POST requests to your endpoint when invoice status changes. All requests come from IP 128.140.76.192.

Verifying Signatures

import { verifyWebhook, extractWebhookSignature, WebhookError } from '@wolvpay/sdk';

// Express
app.post('/webhooks/wolvpay', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString();
  const signature = extractWebhookSignature(req.headers);

  let event;
  try {
    event = verifyWebhook(rawBody, signature, process.env.WOLVPAY_WEBHOOK_SECRET!);
  } catch (err) {
    if (err instanceof WebhookError) {
      return res.status(401).send('Unauthorized');
    }
    return res.status(500).send();
  }

  if (event.status === 'PAID') {
    fulfillOrder(event.invoice_id);
  }

  res.status(200).send('OK');
});

Next.js App Router

// app/api/webhooks/wolvpay/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { verifyWebhook, extractWebhookSignature, WebhookError } from '@wolvpay/sdk';

export async function POST(request: NextRequest) {
  const rawBody = await request.text(); // MUST use .text() not .json()
  const signature = extractWebhookSignature(request.headers);

  let event;
  try {
    event = verifyWebhook(rawBody, signature, process.env.WOLVPAY_WEBHOOK_SECRET!);
  } catch (err) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  switch (event.status) {
    case 'PAID':
      await fulfillOrder(event.invoice_id);
      break;
    case 'EXPIRED':
      await markExpired(event.invoice_id);
      break;
  }

  return NextResponse.json({ received: true });
}

Webhook Payload

interface WebhookPayload {
  invoice_id: string;
  amount: number;
  description: string | null;
  status: 'AWAITING_PAYMENT' | 'CONFIRMING_PAYMENT' | 'PAID' | 'UNDERPAID' | 'EXPIRED';
  coin: string;
  coin_amount: number;
  coin_received: number;
  coin_address: string;
  redirect_url: string | null;
  created_at: string;
}

---

Error Handling

import { WolvPayClient, ApiError, WolvPayError, WebhookError } from '@wolvpay/sdk';

try {
  const invoice = await client.createInvoice({ amount: 50 });
} catch (err) {
  if (err instanceof ApiError) {
    console.error(err.statusCode); // 400, 401, 404, 429, etc.
    console.error(err.message);    // Human-readable API message
    console.error(err.errorData);  // Raw error object from the API
  } else if (err instanceof WolvPayError) {
    console.error('SDK error:', err.message); // Network or parse error
  }
}

Class	When
WolvPayError	Base — network failures, JSON parse errors
ApiError	API returned 4xx or 5xx
WebhookError	Signature verification failed

---

TypeScript Types

All types are exported from the package root:

import type {
  Coin,
  Invoice,
  InvoiceList,
  InvoiceStatus,
  CreateInvoiceParams,
  WebhookPayload,
  Pagination,
} from '@wolvpay/sdk';

---

Building from Source

npm install
npm run build   # outputs to dist/
npm run lint    # type-check only

---

Invoice Status Reference

Status	Description
AWAITING_SELECTION	Customer has not selected a cryptocurrency.
AWAITING_PAYMENT	Crypto selected, waiting for payment.
CONFIRMING_PAYMENT	Payment detected, waiting for confirmations.
PAID	Payment confirmed and complete.
UNDERPAID	Payment received but below required amount.
EXPIRED	Invoice expired without payment.

---

Examples

See the examples/ directory:

• create-invoice.ts — Hosted invoice and retrieval
• white-label.ts — White-label flow with coin selection
• webhook-handler.ts — Webhook verification (Node.js + Next.js)

---

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you'd like to change.

---

Links

• WolvPay Website
• API Documentation
• Dashboard
• Discord Community
• Report an Issue

---

License

MIT — see LICENSE.