A Modern WeChat Pay SDK Built the Right Way: ESM + TypeScript from the Ground Up

Published on ClawList.io | Category: Development

---

If you've ever integrated WeChat Pay into a Node.js project, you already know the pain. The official documentation is dense, most community SDKs are aging CommonJS packages with sprawling dependencies, and TypeScript support is often an afterthought bolted on with a loose .d.ts file. Developer @vikingmute got tired of waiting for something better and built it himself — a clean, lightweight WeChat Pay SDK written in pure ESM and TypeScript, designed to power his own product TinyShip and shared openly with the community.

This isn't a quick weekend wrapper. It supports the full range of WeChat Pay scenarios — Native, APP, JSAPI, and H5 — along with the latest WeChat Pay Public Key mode, and ships with three ready-to-run demo projects covering Hono, Next.js, and Nuxt. Let's break down why this matters and what it means for developers building modern JavaScript applications.

---

Why the WeChat Pay Ecosystem Needed a Fresh SDK

WeChat Pay is non-negotiable for any product targeting Chinese consumers. Whether you're building a SaaS tool, an e-commerce storefront, or a subscription service, you will eventually need to handle WeChat payments. The problem has never been WeChat's capabilities — it's the developer experience getting there.

Most existing Node.js SDKs share a few common problems:

• CommonJS-only: Incompatible with modern ESM-first runtimes and frameworks without workarounds
• Heavy dependency trees: Some packages pull in dozens of transitive dependencies for what amounts to a few HTTP calls and some cryptographic signing
• Stale API support: Many SDKs lag behind WeChat's API updates, particularly around the newer public key authentication model
• Poor TypeScript ergonomics: Types that are incomplete, incorrect, or simply missing force developers to cast everything to any and hope for the best

The new SDK addresses each of these directly. By starting from scratch with modern tooling and a clear scope, @vikingmute avoided inheriting technical debt that has made older packages frustrating to maintain and use.

---

What's Inside: Architecture and Feature Breakdown

Pure ESM + TypeScript, Lightweight by Design

The SDK is written entirely in TypeScript and distributed as pure ESM modules. This means it works natively with modern runtimes like Bun and Deno, integrates cleanly into Next.js App Router and Nuxt server routes without configuration gymnastics, and plays well with tree-shaking for minimal bundle impact.

The dependency footprint is intentionally minimal. Payment integrations don't need a framework — they need reliable HTTP, proper cryptographic signing (RSA-OAEP for sensitive fields, SHA-256 for signatures), and well-typed request/response models. Keeping dependencies lean also reduces your attack surface, which matters when you're handling financial transactions.

Payment Method Coverage

The SDK covers the four primary WeChat Pay scenarios developers encounter in production:

• Native Pay: Generates a QR code URL for desktop or in-store payment flows
• APP Pay: Returns the parameters needed to invoke the WeChat Pay SDK inside a native iOS or Android application
• JSAPI Pay: Handles in-WeChat-browser payments, the most common flow for mini-programs and WeChat-embedded web apps
• H5 Pay: For mobile web browsers outside of WeChat, redirecting users through WeChat's mobile payment flow

Merchant transfers (企业转账/商家转账) are on the roadmap but not yet implemented — a reasonable scoping decision for a first release.

WeChat Pay Public Key Mode Support

This is a detail worth highlighting. WeChat rolled out the public key mode as the recommended authentication approach, replacing the older platform certificate model. Many existing SDKs still rely on the certificate-based flow, which requires periodically downloading and rotating platform certificates. The new public key mode is simpler and more stable. Supporting it from day one puts this SDK ahead of most alternatives currently available.

Three Demo Projects

One of the most useful aspects of this release is the included demo projects. Rather than a single contrived example, the SDK ships with three minimal but complete integrations:

Hono — The ultralight web framework increasingly popular in edge and serverless environments. The Hono demo shows how to wire up a WeChat Pay endpoint with minimal boilerplate, making it useful as a reference for Cloudflare Workers or similar deployments.

Next.js — The demo targets the App Router and demonstrates how to handle WeChat Pay callbacks (notifications) inside a Route Handler, along with initiating payment orders server-side.

Nuxt — Covers the Nuxt server route equivalent, useful for teams building Vue-based applications that need WeChat Pay on the backend.

Having all three demonstrates that the SDK isn't tied to any specific framework abstraction — it's just TypeScript functions that work wherever Node.js-compatible runtimes run.

---

Practical Usage: What Integration Looks Like

While the full API will be documented in the official release, the design philosophy points toward something clean and composable. A typical JSAPI payment initiation flow would look roughly like this:

import { WechatPay } from 'your-wechat-pay-sdk'

const pay = new WechatPay({
  appId: process.env.WECHAT_APP_ID!,
  mchId: process.env.WECHAT_MCH_ID!,
  privateKey: process.env.WECHAT_PRIVATE_KEY!,
  publicKeyId: process.env.WECHAT_PUBLIC_KEY_ID!,
})

// Create a JSAPI order
const order = await pay.jsapi.createOrder({
  description: 'Premium Subscription',
  outTradeNo: 'ORDER_20260304_001',
  amount: { total: 9900, currency: 'CNY' },
  payer: { openid: userOpenId },
  notifyUrl: 'https://yourdomain.com/api/wechat/notify',
})

// Returns parameters ready to pass to WeixinJSBridge
console.log(order.payParams)

The callback handler in a Next.js Route Handler would be equally straightforward — receive the notification, verify the signature using the SDK's built-in utilities, update your order status, and return the expected acknowledgment response.

This kind of ergonomic API design is what separates purpose-built TypeScript SDKs from auto-generated or ported alternatives.

---

Who Should Watch This Release

If you're building any of the following, this SDK belongs on your radar:

• SaaS products targeting the Chinese market that need a reliable, maintainable payment layer
• Next.js or Nuxt applications where a modern ESM-compatible package removes a category of integration headaches
• Edge or serverless deployments on Cloudflare Workers, Vercel Edge Functions, or similar runtimes where ESM compatibility and minimal dependencies are requirements
• Indie developers and small teams who want to understand exactly what their payment code is doing without deciphering a dependency graph of unknown packages

The SDK isn't released yet as of this writing — @vikingmute noted it's nearly ready and will be published in the coming days. Given the thoughtfulness in scope and the production context (it's being used in TinyShip), it's worth watching the original thread for the release announcement.

---

Conclusion

The WeChat Pay SDK space has been due for a modern rewrite for a while. This project — pure ESM, TypeScript-first, lightweight dependencies, public key mode support, and real framework demos — checks the boxes that matter for developers building production applications today. It's a practical solution born from real frustration, shaped by real product requirements.

Follow @vikingmute on X for the official release. When it drops, it's likely to become the default recommendation for WeChat Pay integration in modern JavaScript projects.

---

Found this useful? ClawList.io covers developer tools, AI automation, and OpenClaw skills for builders moving fast. Subscribe for weekly picks.