npm install @payzcore/node

import { PayzCore } from '@payzcore/node';

// Project API (payment monitoring)
const client = new PayzCore('pk_live_YOUR_KEY');

// With options
const client = new PayzCore('pk_live_YOUR_KEY', {
  baseUrl: 'https://api.payzcore.com', // optional, default
  timeout: 30000,                       // optional, ms
  maxRetries: 2,                        // optional, retries on 5xx
});

// Admin API (project management)
const admin = new PayzCore('mk_YOUR_MASTER_KEY', { masterKey: true });

const { payment } = await client.payments.create({
  amount: 50,
  network: 'TRC20',
  token: 'USDT',                // optional, defaults to 'USDT'
  externalRef: 'customer-123',
  externalOrderId: 'ORD-456',  // optional, enables idempotency
  expiresIn: 3600,              // optional, seconds (300-86400)
  metadata: { type: 'topup' }, // optional, max 4KB
});

console.log(payment.id);       // UUID
console.log(payment.address);  // blockchain address
console.log(payment.amount);   // "50.00" (string)
console.log(payment.status);   // "pending"
console.log(payment.qrCode);   // base64 PNG

const { payment } = await client.payments.get('payment-uuid');

console.log(payment.status);        // 'pending' | 'confirming' | 'paid' | 'overpaid' | 'partial' | 'expired' | 'cancelled'
console.log(payment.paidAmount);    // total received
console.log(payment.transactions);  // array of blockchain txs

const result = await client.payments.list({
  status: 'paid',  // optional filter
  limit: 25,       // optional, default 50
  offset: 0,       // optional, for pagination
});

for (const payment of result.payments) {
  console.log(payment.id, payment.status, payment.paidAmount);
}

const result = await client.payments.cancel('payment-uuid');
// Only works on 'pending' payments

const result = await client.payments.confirm('payment-uuid', 'abc123def...');

console.log(result.status);    // 'confirming' | 'pending' | 'paid'
console.log(result.verified);  // true if found on blockchain

import { verifyWebhookSignature, constructEvent } from '@payzcore/node';

import { verifyWebhookSignature } from '@payzcore/node';

const isValid = verifyWebhookSignature(
  rawBody,                                    // raw request body string
  req.headers.get('x-payzcore-signature')!,   // signature header
  'whsec_YOUR_SECRET',                        // webhook secret
  { timestamp: req.headers.get('x-payzcore-timestamp')! },
);

import { constructEvent } from '@payzcore/node';

// Verifies signature and returns a typed WebhookPayload
// Throws WebhookSignatureError if signature is invalid
const event = constructEvent(
  rawBody,
  req.headers.get('x-payzcore-signature')!,
  'whsec_YOUR_SECRET',
  { timestamp: req.headers.get('x-payzcore-timestamp')! },
);

console.log(event.event);          // 'payment.completed'
console.log(event.paymentId);      // UUID
console.log(event.paidAmount);     // '50.00'

const event = constructEvent(body, signature, secret, {
  timestamp: req.headers.get('x-payzcore-timestamp')!,
  toleranceMs: 300_000, // 5 minutes (default)
});

import { constructEvent, WebhookSignatureError } from '@payzcore/node';

export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get('x-payzcore-signature')!;

  let event;
  try {
    const timestamp = req.headers.get('x-payzcore-timestamp')!;
    event = constructEvent(body, signature, 'whsec_YOUR_SECRET', { timestamp });
  } catch (err) {
    if (err instanceof WebhookSignatureError) {
      return new Response('Invalid signature', { status: 401 });
    }
    throw err;
  }

  switch (event.event) {
    case 'payment.completed':
      await creditUser(event.externalRef, parseFloat(event.paidAmount));
      break;
    case 'payment.overpaid':
      await creditUser(event.externalRef, parseFloat(event.paidAmount));
      await logOverpayment(event.paymentId, event.expectedAmount, event.paidAmount);
      break;
    case 'payment.partial':
      await notifyPartial(event.externalRef, event.expectedAmount, event.paidAmount);
      break;
    case 'payment.expired':
      await handleExpired(event.externalRef, event.paymentId);
      break;
  }

  return new Response('OK', { status: 200 });
}

import {
  PayzCoreError,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NotFoundError,
} from '@payzcore/node';

try {
  const { payment } = await client.payments.create({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Invalid request:', error.message, error.details);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log('Rate limit exceeded, daily:', error.isDaily);
  } else if (error instanceof NotFoundError) {
    console.log('Payment not found');
  } else if (error instanceof PayzCoreError) {
    console.log(`API error ${error.status}: ${error.message}`);
  }
}

import type {
  Payment,
  PaymentDetail,
  CreatePaymentParams,
  ListPaymentsResponse,
  WebhookPayload,
  Network,
  Token,
  PaymentStatus,
} from '@payzcore/node';