@polymersuite/polymerpay-sdk

The official Polymer Pay SDK. Provides a typed, promise-based client for integrating with the Polymer Pay API from your server-side code, edge functions, or modern browsers.

Installation

Install the package with your preferred package manager:

# npm
npm install @polymersuite/polymerpay-sdk

# yarn
yarn add @polymersuite/polymerpay-sdk

# pnpm
pnpm add @polymersuite/polymerpay-sdk

# bun
bun add @polymersuite/polymerpay-sdk

Quick Start

Initialize the client with your API key. You can find your API key in the Polymer Pay Merchant Dashboard.

import { PolymerPay } from "@polymersuite/polymerpay-sdk";

// Initialize the client
const polymerpay = new PolymerPay({
  api_key: process.env.POLYMER_API_KEY,
  environment: "sandbox" // Set environment to 'sandbox' for development or testing
});

// Create a hosted checkout session
const checkout = await polymerpay.checkout.create({
  amount: 10_00, // Amount in cents (e.g., $10.00)
  currency: "USD",
  reference: "order-123",
  success_url: "https://your-site.com/success",
  cancel_url: "https://your-site.com/cancel",
});

console.log("Checkout URL:", checkout.url);

Features

Payment Links

Create reusable payment links for your customers.

const link = await polymerpay.paymentLink.create({
  amount: 25_00,
  currency: "USD",
  description: "Premium Subscription",
});

QR Codes

Generate dynamic QR codes for in-person or scan-to-pay scenarios.

const qr = await polymerpay.qrCode.create({
  amount: 5_00,
  currency: "KHR",
  description: "Coffee",
});

Webhook Verification

Securely verify incoming webhooks from Polymer Pay to ensure they are authentic.

import { Webhooks } from "@polymersuite/polymerpay-sdk";

// In your webhook handler (e.g., Express, Next.js API route)
const isValid = polymerpay.webhooks.verifySignature({
  payload: rawBody, // The raw, unparsed request body string
  signature: req.headers["x-polymer-signature"],
  secret: process.env.WEBHOOK_SECRET,
});

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

Error Handling

The SDK throws PolymerError instances when API requests fail. You can catch these to handle specific error types.

import { PolymerError } from "@polymersuite/polymerpay-sdk";

try {
  await polymerpay.checkout.create({
    /* ... */
  });
} catch (error) {
  if (error instanceof PolymerError) {
    console.error(`API Error (${error.status}):`, error.message);
    console.error("Details:", error.details);
  } else {
    console.error("Unexpected error:", error);
  }
}

Environment Support

The SDK is built to run anywhere:

• Node.js (18+)
• Bun
• Edge Runtimes (Cloudflare Workers, Vercel Edge, Deno)
• Modern Browsers

It ships with CommonJS (CJS), ECMAScript Modules (ESM), and full TypeScript declaration files.

Types

The SDK exports all necessary TypeScript types for requests and responses:

import type {
  CheckoutCreateParams,
  CheckoutResponse,
  PaymentLinkCreateParams,
  PaymentLinkResponse,
  QrCodeCreateParams,
  QrCodeResponse,
  PolymerErrorDetails,
  PolymerErrorType,
} from "@polymersuite/polymerpay-sdk";