Integrate WAM payment links into your Node.js applications with our official SDK. Full TypeScript support with HMAC-SHA256 signing.

WAM Payment SDK

Official Node.js SDK for integrating WAM payment links into your applications. This SDK provides a simple and secure way to generate signed payment links for the WAM payment platform.

Features

Generate signed payment links with HMAC-SHA256 signatures
Full TypeScript support with type definitions
Comprehensive input validation and error handling
Works in Node.js environments (server-side only)
Lightweight with no external dependencies
Support for staging and production environments

Installation

npm install @zed-io/wam-payment-sdk

yarn add @zed-io/wam-payment-sdk

pnpm add @zed-io/wam-payment-sdk

Quick Start

import { WamPaymentSDK } from '@zed-io/wam-payment-sdk';

// Initialize the SDK
const wamPayment = new WamPaymentSDK({
  businessId: 'your-business-id',
  privateKey: 'your-private-key',
  environment: 'staging' // 'production' | 'staging' | 'development'
});

// Generate a payment link
const paymentLink = wamPayment.generatePaymentLink({
  amount: 5000,      // Amount in cents (50.00)
  currency: 'TTD',   // 'TTD' or 'USD'
  reference: 'ORDER-123',
  returnUrl: 'https://your-site.com/success'
});

console.log('Payment URL:', paymentLink.url);

Configuration

SDK Configuration Options

Property	Type	Required	Description
`businessId`	string	Yes	Your WAM business ID
`privateKey`	string	Yes	Your WAM private key for signing
`environment`	string	No	`'production'` \| `'staging'` \| `'development'` (defaults to `'production'`)

Environment URLs

Environment	Base URL
`production` (default)	`https://billing.wam.money`
`staging`	`https://staging.billing.wam.money`
`development`	`https://staging.billing.wam.money`

Payment Link Parameters

Property	Type	Required	Description
`amount`	number	Yes	Payment amount in cents
`currency`	`'TTD'` \| `'USD'`	Yes	Currency code
`reference`	string	Yes	Unique reference for the payment
`returnUrl`	string	No	URL to redirect after payment

TypeScript Types

import {
  WamPaymentSDK,
  PaymentLinkParams,
  PaymentLinkResponse,
  WamPaymentConfig,
  WamPaymentError,
  WamPaymentErrorCode
} from '@zed-io/wam-payment-sdk';

// Configuration type
interface WamPaymentConfig {
  businessId: string;
  privateKey: string;
  environment?: 'production' | 'staging' | 'development';
}

// Payment parameters type
interface PaymentLinkParams {
  amount: number;
  currency: 'TTD' | 'USD';
  reference: string;
  returnUrl?: string;
}

// Response type
interface PaymentLinkResponse {
  url: string;
  signature: string;
  payload: string;
}

Next.js Integration

This example demonstrates how to integrate the SDK into a Next.js application with App Router.

Environment Variables

Add to your .env.local:

MERCHANT_ID=your-business-id
MERCHANT_SECRET_KEY=your-private-key
NEXT_PUBLIC_APP_URL=http://localhost:3000

SDK Wrapper Module

Create lib/wam.ts to initialize the SDK:

import { WamPaymentSDK } from '@zed-io/wam-payment-sdk';

const getSDK = () => {
  const businessId = process.env.MERCHANT_ID;
  const privateKey = process.env.MERCHANT_SECRET_KEY;

  if (!businessId || !privateKey) {
    throw new Error(
      'MERCHANT_ID and MERCHANT_SECRET_KEY must be set'
    );
  }

  return new WamPaymentSDK({
    businessId,
    privateKey,
    environment: 'staging',
  });
};

export async function createPaymentLink(params: {
  amount: number;  // dollars
  reference: string;
  returnUrl?: string;
}) {
  const sdk = getSDK();
  const amountInCents = Math.round(params.amount * 100);

  return sdk.generatePaymentLink({
    amount: amountInCents,
    currency: 'TTD',
    reference: params.reference,
    returnUrl: params.returnUrl,
  });
}

API Route

Create app/api/payment/create/route.ts:

import { NextRequest, NextResponse } from 'next/server';
import { createPaymentLink } from '@/lib/wam';

export async function POST(request: NextRequest) {
  try {
    const { amount, reference } = await request.json();

    if (!amount || !reference) {
      return NextResponse.json(
        { error: 'Missing required fields' },
        { status: 400 }
      );
    }

    const result = await createPaymentLink({
      amount: parseFloat(amount),
      reference,
      returnUrl: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
    });

    return NextResponse.json({
      success: true,
      paymentUrl: result.url,
    });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to create payment' },
      { status: 500 }
    );
  }
}

Error Handling

import { WamPaymentError } from '@zed-io/wam-payment-sdk';

try {
  const paymentLink = wamPayment.generatePaymentLink({
    amount: -100,  // Invalid
    currency: 'TTD',
    reference: 'ORDER-123',
  });
} catch (error) {
  if (error instanceof WamPaymentError) {
    console.error('Code:', error.code);
    console.error('Message:', error.message);

    if (error.validationErrors) {
      error.validationErrors.forEach(err => {
        console.error(`${err.field}: ${err.message}`);
      });
    }
  }
}

Error Codes

Code	Description
`INVALID_CONFIG`	Invalid SDK configuration
`INVALID_AMOUNT`	Invalid payment amount (must be positive)
`INVALID_CURRENCY`	Invalid currency code (must be TTD or USD)
`INVALID_REFERENCE`	Invalid reference (empty or too long)
`INVALID_RETURN_URL`	Invalid return URL format
`SIGNING_ERROR`	Error during signature generation

API Reference

`new WamPaymentSDK(config: WamPaymentConfig)`

Creates a new instance of the WAM Payment SDK.

`generatePaymentLink(params: PaymentLinkParams): PaymentLinkResponse`

Generates a signed payment link for WAM payment processing.

Parameters:

params.amount - Payment amount in cents (integer)
params.currency - Currency code ('TTD' or 'USD')
params.reference - Unique payment reference string
params.returnUrl - Optional URL for redirect after payment

Returns:

url - Complete payment URL with signature
signature - HMAC-SHA256 signature
payload - Signed payload string

`getConfig(): Omit<WamPaymentConfig, 'privateKey'>`

Returns the current configuration without the private key.

Security Best Practices

Never expose your private key in client-side code - always use server-side API routes
Use environment variables for all sensitive configuration
Validate all inputs before generating payment links
Use HTTPS for all payment-related communications
Generate unique references for each payment

Payment Flow

User initiates payment on your application
Your server calls the SDK to generate a signed payment link
User is redirected to the WAM payment page
User completes payment on WAM
User is redirected back to your returnUrl

Resources

NPM Package
Contact Support for API credentials

WAM Payment SDK

On this page