Plugipay
ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Plugipay Docs
⌘K

Node.js SDK

@forjio/plugipay-node is the official Node.js client for the Plugipay API. It wraps every public resource — customers, plans, checkout sessions, subscriptions, invoices, refunds, payouts, webhooks, ledger, reports, templates — behind a single typed PlugipayClient, signs every request for you, and ships first-class TypeScript types out of the box.

Use it when your backend runs on Node 20+. If you're targeting another runtime, see the Python or Go SDKs, or fall back to the raw HTTP API.

Why use the SDK

You can integrate Plugipay with fetch alone — the wire format is plain JSON and we document the HMAC signing recipe in full. But the SDK gives you a few things you'd otherwise hand-roll:

  • Transparent HMAC-SHA256 signing. You hand it keyId + secret; it computes bodyHash, builds the string-to-sign, and sets the Authorization and X-Plugipay-Timestamp headers on every call.
  • Idempotency keys by default. Every mutating request gets a fresh Idempotency-Key. Retries are safe without you thinking about it.
  • Typed resources. Every method's input and return shape is declared in TypeScript. Autocomplete tells you what fields a CheckoutSession carries before you read the docs.
  • Envelope unwrapping. The API returns { data, error, meta }; the SDK returns just data (or throws on error). List endpoints additionally surface { data, cursor, hasMore } so cursor iteration is one line.
  • A typed PlugipayError. Every API or network failure becomes a single exception class with status, code, message, and requestId — switch on error.code for branch logic.
  • A verifyWebhook helper. Pass raw body + signature header + secret; get back a typed WebhookEvent discriminated union you can switch on.
  • A platform-partner mode. Mint one platform-admin key and call .forMerchant(accountId) to scope requests to a specific merchant workspace.

The whole library is dependency-free at runtime — it uses Node's built-in crypto and the global fetch. Bundlers tree-shake unused resources naturally because the client is a single class.

Install

npm install @forjio/plugipay-node

Requires Node >=20.0.0. See Installation for ESM/CJS notes, TypeScript settings, and bundler tips.

A minimal example

import { PlugipayClient } from '@forjio/plugipay-node';

const plugipay = new PlugipayClient({
  keyId: process.env.PLUGIPAY_KEY_ID!,
  secret: process.env.PLUGIPAY_SECRET!,
});

const session = await plugipay.checkoutSessions.create({
  amount: 199000,
  currency: 'IDR',
  methods: ['qris', 'va'],
  successUrl: 'https://myshop.com/thanks',
  cancelUrl: 'https://myshop.com/cart',
});

console.log(session.hostedUrl); // → https://plugipay.com/c/cs_01H...

Three lines of imports, three lines of config, one call to a hosted checkout URL. See Quickstart for the end-to-end version with a customer record.

What's in the box

The SDK exports three top-level symbols:

Export Purpose
PlugipayClient The HTTP client. Every resource is a property on it (plugipay.customers, plugipay.plans, ...).
verifyWebhook Standalone helper for inbound webhooks. Returns a typed WebhookEvent.
PlugipayError The single error class thrown by every method.

Plus the full set of resource types (Customer, CheckoutSession, Invoice, Subscription, Refund, Payout, ...) and discriminated-union event types (WebhookEvent).

Per-page guide

The SDK docs are split across seven pages, each focused on one concern. Read them in order if you're starting from scratch; jump in if you know what you're looking for.

Page What it covers
Installation npm install, Node version, ESM vs CJS, TypeScript settings, bundling, tree-shaking.
Quickstart Customer + checkout session end-to-end. The "hello world" path.
Authentication How PlugipayClient signs requests, env-var conventions, per-call onBehalfOf overrides for platform partners, custom timeouts and base URLs.
Errors PlugipayError shape, switching on code, network vs API errors, retry patterns.
Pagination The { data, cursor, hasMore } shape, manual loops, async iteration.
Webhooks verifyWebhook, Express raw-body integration, type-narrowing on event types, handler examples per event.
Reference Every resource namespace and method on PlugipayClient, with one-line descriptions and links to API resource pages.

Versioning

@forjio/plugipay-node follows semantic versioning. Pre-1.0 (we're at 0.x today) means minor versions may include small breaking changes — we batch them and document each one in the changelog. Once we cut 1.0 (target: mid-2026) the major/minor/patch contract becomes strict.

Pin a caret range (^0.5.0) and read the changelog before bumping a minor.

Open source

The SDK lives in the same monorepo as Plugipay itself, at saas-plugipay/sdk/node. Issues, PRs, and questions are welcome on GitHub.

Next

Plugipay — Payments that don't tax your success