@crypax/node

Server-side SDK for Node.js. Create payments, verify webhooks, and check on-chain confirmations.

Installation

$ npm install @crypax/node

Setup

Initialize the client with your secret key. Never use secret keys in client-side code.

crypax.ts

import { Crypax } from '@crypax/node';

const crypax = new Crypax('sk_live_your_secret_key', {
  apiUrl: 'https://api.crypax.io',  // optional, defaults to production
});

Chain Constants

The SDK exports pre-defined chain constants so you don't need to remember chain IDs. Use these constants when creating payments.

import { PLUMISE_MAINNET, PLUMISE_TESTNET, CHAINS, SUPPORTED_CHAIN_IDS } from '@crypax/node';

// Use chain constants instead of raw chain IDs
console.log(PLUMISE_MAINNET.chainId);  // 41956
console.log(PLUMISE_TESTNET.chainId);  // 419561

// Each constant includes full chain info
// { chainId, name, symbol, decimals, rpcUrl, explorerUrl, isTestnet }

// CHAINS object for iteration
Object.values(CHAINS).forEach(chain => {
  console.log(chain.name, chain.chainId);
});

// SUPPORTED_CHAIN_IDS = [41956, 419561]

Available Chains

Constant	Name	Chain ID	Symbol	Testnet
`PLUMISE_MAINNET`	Plumise Mainnet	41956	PLM	No
`PLUMISE_TESTNET`	Plumise Testnet	419561	PLM	Yes

Payments

`payments.create(params)`

Create a new payment. Returns a Payment object including a clientSecret to pass to the frontend.

import { PLUMISE_MAINNET } from '@crypax/node';

const payment = await crypax.payments.create({
  amount: '1.0',                                  // Amount as string
  recipientAddress: '0xYourAddress',              // Recipient wallet
  chainId: PLUMISE_MAINNET.chainId,               // 41956
  currency: 'native',                             // 'native' | token address
  orderId: 'order_123',                           // Your internal order ID
  description: 'Premium Plan',                   // Human-readable description
  metadata: { userId: 'user_456' },               // Arbitrary key-value pairs
  expiresInMinutes: 30,                           // Expiry (default: 60)
});

console.log(payment.id);           // Payment UUID
console.log(payment.clientSecret); // 'cs_live_...' — send to frontend

CreatePaymentParams

Parameter	Type	Required	Description
`amount`	string	Required	Payment amount as a decimal string (e.g. '1.0')
`recipientAddress`	string	Required	Wallet address to receive the payment
`chainId`	number	Required	Use chain constants: PLUMISE_MAINNET.chainId (41956), PLUMISE_TESTNET.chainId (419561)
`currency`	string	Optional	'native' for PLM, or an ERC20 token address
`orderId`	string	Optional	Your internal order identifier
`description`	string	Optional	Human-readable description
`metadata`	Record<string, unknown>	Optional	Arbitrary key-value data attached to the payment
`expiresInMinutes`	number	Optional	Minutes until payment expires (default: 60)

`payments.retrieve(id)`

Retrieve a payment by ID. Useful for checking status after webhook delivery.

const payment = await crypax.payments.retrieve('payment-uuid');
console.log(payment.status); // 'created' | 'processing' | 'confirmed' | 'expired' | 'failed'
console.log(payment.txHash); // '0x...' (after confirmation)

`payments.list(params?)`

List payments with optional filters for status, date range, and pagination.

const { data, total } = await crypax.payments.list({
  limit: 20,
  offset: 0,
  status: 'confirmed',  // optional filter
});

data.forEach(payment => {
  console.log(payment.id, payment.amount, payment.status);
});

Webhooks

`webhooks.constructEvent(payload, signature, secret)`

Parse and verify an incoming webhook request. Pass the raw request body (Buffer), the signature header, and your webhook secret. Throws if the signature is invalid.

webhook.ts

import { Crypax } from '@crypax/node';
import express from 'express';

const app = express();
const crypax = new Crypax('sk_live_your_secret_key');

app.post('/webhooks/crypax', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-crypax-signature'] as string;

  try {
    const event = crypax.webhooks.constructEvent(
      req.body,
      signature,
      'whsec_your_webhook_secret'
    );

    switch (event.type) {
      case 'payment.confirmed':
        console.log('Confirmed:', event.data.id, event.data.txHash);
        break;
      case 'payment.expired':
        console.log('Expired:', event.data.id);
        break;
      case 'payment.failed':
        console.log('Failed:', event.data.id);
        break;
    }

    res.json({ received: true });
  } catch (err) {
    res.status(400).json({ error: 'Invalid signature' });
  }
});

`webhooks.verifySignature(payload, signature, secret)`

Verify the HMAC-SHA256 signature without parsing the event. Returns true if valid.

const isValid = crypax.webhooks.verifySignature(
  rawBody,      // Buffer or string
  signature,    // x-crypax-signature header value
  webhookSecret // whsec_... from dashboard
);

if (!isValid) {
  throw new Error('Invalid webhook signature');
}

Verification

`verification.verifyPayment(paymentId)`

Verify a native PLM payment on-chain. Returns the payment result with txHash and blockNumber.

const result = await crypax.verification.verifyPayment('payment-uuid');
console.log(result.status);      // 'confirmed'
console.log(result.txHash);      // '0x...'
console.log(result.blockNumber); // 12345678

`verification.verifyERC20Payment(paymentId)`

Verify an ERC20 token payment on-chain. Returns token address and transferred amount.

const result = await crypax.verification.verifyERC20Payment('payment-uuid');
console.log(result.tokenAddress); // ERC20 contract address
console.log(result.amount);       // Transferred amount

Types

// Payment object
interface Payment {
  id: string;
  clientSecret: string;
  amount: string;
  recipientAddress: string;
  senderAddress?: string;
  chainId: number;
  currency: string;
  orderId?: string;
  description?: string;
  metadata?: Record<string, unknown>;
  status: 'created' | 'processing' | 'confirmed' | 'expired' | 'failed';
  txHash?: string;
  blockNumber?: number;
  expiresAt: string;
  confirmedAt?: string;
  createdAt: string;
}

// Webhook event
interface WebhookEvent {
  id: string;
  type: 'payment.created' | 'payment.confirmed' | 'payment.expired' | 'payment.failed';
  data: Payment;
  createdAt: string;
}

React SDK →Vue SDK →API Reference →