npm package: @polymersuite/polymerpay-sdk
Description: Polymer Pay SDK
Latest version: 1.0.3

# @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:

```bash
# 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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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:

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