SaligPay Node SDK Overview

Official Node.js SDK for SaligPay payment integration. A type-safe, production-ready client for processing payments, managing checkout sessions, and handling webhooks.

npm · version · TypeScript · Node.js

Features

• Type-safe — Full TypeScript support with exported types
• Dual build — Works with both ESM and CommonJS
• Authentication — Client credentials OAuth flow with automatic token refresh
• Checkout — Create and manage payment sessions
• Payment Intents — Create, confirm, and manage payment intents
• Subscriptions — Full subscription lifecycle management (initiate, process, update, cancel)
• Plans — Create, list, and retrieve subscription plans
• Payouts — Retrieve payout list, details, transactions, and schedules
• Wallets — Manage wallet accounts, balances, and transfers
• Transfers — Create batch transfers between accounts
• Banks — List receiving institutions for Instapay/Pesonet
• Webhooks — Parse, verify, and handle webhook events with signature validation
• Error handling — Custom error classes with detailed context
• Zero dependencies — Minimal runtime footprint (uses native fetch)

Installation

Code
 
npm install saligpay-node
# or
yarn add saligpay-node
# or
pnpm add saligpay-node
# or
bun add saligpay-node

Quick Start

Code
 
import { SaligPay } from "saligpay-node";

// Initialize the SDK
const saligpay = new SaligPay({
    clientId: process.env.SALIGPAY_CLIENT_ID!,
    clientSecret: process.env.SALIGPAY_CLIENT_SECRET!,
    env: "sandbox", // or 'production'
});

// Authenticate
await saligpay.authenticate();

// Create a checkout session
const checkout = await saligpay.checkout.create({
    externalId: "order-123",
    amount: 10000, // in centavos (₱100.00)
    description: "Premium Plan Subscription",
    webhookUrl: "https://yourapp.com/webhooks/saligpay",
    returnUrl: "https://yourapp.com/payment/success",
    contact: {
        name: "John Doe",
        email: "john@example.com",
        contact: "+639123456789",
    },
});

console.log("Checkout URL:", checkout.checkoutUrl);
// Redirect user to checkout.checkoutUrl to complete payment

Requirements

• Node.js 18.0.0 or higher (uses native fetch API)

SDK Architecture

Code
 
SaligPay (main client)
├── apiClient: SaligPayApiClient    # Low-level HTTP client
├── auth: AuthResource              # OAuth authentication
├── checkout: CheckoutResource      # Checkout sessions
├── webhooks: WebhookResource       # Webhook parsing/validation
├── paymentIntents: PaymentIntentResource
├── subscriptions: SubscriptionResource
├── payouts: PayoutResource
├── wallets: WalletResource
├── transfers: TransferResource
└── banks: BankResource

Table of Contents

• Configuration
• Authentication
• Checkout Sessions
• Payment Intents
• Subscriptions
• Plans
• Payouts
• Wallets
• Transfers
• Banks
• Webhooks
• Error Handling
• TypeScript Usage
• CommonJS Usage
• Testing
• Server-Side Usage — Singleton, React Router 7, Next.js (App & Pages), Hono, NestJS, Elysia
• Troubleshooting
• Security Best Practices
• API Reference