KuvarPay Server SDK

Official Node.js SDK for integrating KuvarPay, the ultimate fiat gateway for the crypto economy. This SDK allows you to handle checkout sessions, direct crypto-to-fiat transactions, recurring subscriptions, and split payments with ease.

Detailed documentation is available at developers.kuvarpay.com.

🚀 Installation

npm install @kuvarpay/sdk

🛠️ Quick Start (Speed Mode)

Initiate a payment and get a crypto deposit address in one line of code:

const { KuvarPayServer } = require('@kuvarpay/sdk');

const kv = new KuvarPayServer({
  businessId: 'your_business_id',
  secretApiKey: 'rsp_secret_...' // Starts with rsp_secret_
});

async function startPayment() {
  const payment = await kv.createDirectPayment({
    amount: 5000,
    currency: 'NGN',
    fromCurrency: 'USDT',
    fromNetwork: 'BSC',
    customerEmail: '[email protected]'
  });

  console.log('Send USDT to:', payment.depositAddress);
  console.log('Exact amount:', payment.fromAmount); // e.g. 3.76 USDT
}

⚙️ Configuration

The SDK defaults to the KuvarPay Production API (https://payment.kuvarpay.com).

| Option | Description | Env Fallback | | :--- | :--- | :--- | | businessId | Your KuvarPay Business ID | - | | secretApiKey | Your Production Secret Key | - | | baseUrl | Overrides the API endpoint | KUVARPAY_API_BASE_URL | | timeoutMs | Request timeout (default 60s) | - |

📖 API Reference

💳 Payments & Transactions

| Method | Description | | :--- | :--- | | createDirectPayment(data) | Recommended. Creates a session & transaction in one call. | | createCheckoutSession(data) | Creates a checkout session (returns approvalUrl). | | createTransaction(data) | Manually initiates a crypto transaction for an existing session. | | verifyPayment(sessionId) | Convenience method to check if a payment is confirmed. | | getSessionStatus(sessionId)| Fetches full session/transaction status. |

📈 Subaccounts & Split Payments

| Method | Description | | :--- | :--- | | createSubaccount(data) | Create a vendor subaccount for split settlements. | | listSubaccounts() | Fetch all subaccounts for your business. | | createSplitGroup(data) | Define percentage-based distribution between subaccounts. |

🔄 Subscriptions

| Method | Description | | :--- | :--- | | createDirectSubscription(data) | Initiates a subscription setup and returns an approval URL. | | renewSubscription(subId) | Manually trigger a renewal for an active allowance. | | cancelSubscription(subId) | Hard-cancel a customer subscription. | | createMeteredInvoice(subId, data)| Charge a customer based on usage (Metered billing). |

🏦 Banks & Verification

| Method | Description | | :--- | :--- | | getBanks(currency) | List supported settlement banks for a specific currency. | | resolveBankAccount(data) | Verify bank account names before creating subaccounts. |

🔒 Security: Webhook Verification

Verify that incoming webhooks are genuinely from KuvarPay using HMAC-SHA256:

app.post('/webhooks/kuvarpay', (req, res) => {
  const signature = req.headers['x-kuvarpay-signature'];
  const payload = req.body; // Raw body object

  const isValid = kv.verifyWebhookSignature(payload, signature);

  if (isValid) {
    // Process payment (e.g. status === 'completed')
    res.status(200).send();
  } else {
    res.status(401).send('Invalid signature');
  }
});

🧩 TypeScript Support

This SDK includes a full index.d.ts definition file. You get auto-completion and type checking out of the box.

import { KuvarPayServer } from '@kuvarpay/sdk';

const kv = new KuvarPayServer({ ... });

📄 License

MIT © KuvarPay Development Team