@synko-lab/paymints-node

Server-side SDK for Paymints. Manage customers, subscriptions, and health checks from your backend.

Installation

pnpm add @synko-lab/paymints-node

Requires Node.js >= 18.

Quick Start

import { PaymintsBackend } from "@synko-lab/paymints-node";

const paymints = new PaymintsBackend({
  apiKey: "pmts.your_secret_key",
  projectId: "your_project_id",
});

Customers

List customers

const result = await paymints.customers.list({
  page: 1,
  limit: 20,
  status: "active",
  search: "john",
  provider: "stripe",
  hasActiveSubscription: true,
});

console.log(result.data); // Customer[]
console.log(result.pagination); // { current_page, total, total_pages, ... }
console.log(result.filters.available); // available filter values

Get customer by ID

const customer = await paymints.customers.getById("customer_id");

Get customer by email

const customer = await paymints.customers.getByEmail("[email protected]");

Check if customer exists

const exists = await paymints.customers.exists("customer_id");

Subscriptions

Check subscription status

const status = await paymints.subscriptions.checkStatus({
  customerReference: "user_123",
});

if (status.hasActiveSubscription) {
  console.log("Plan:", status.subscription?.planName);
  console.log("Status:", status.subscription?.status);
  console.log("Renews:", status.subscription?.currentPeriodEnd);
}

Create checkout session

const checkout = await paymints.subscriptions.createCheckout({
  provider: "stripe",
  userEmail: "[email protected]",
  userId: "user_123",
  priceId: "price_xxxxx", // optional
  successUrl: "https://myapp.com/success",
  cancelUrl: "https://myapp.com/cancel",
});

console.log(checkout.url); // redirect URL

Health

const health = await paymints.health.check();
console.log(health.status); // "healthy" | "degraded"
console.log(health.providers); // provider status details

Configuration

const paymints = new PaymintsBackend({
  apiKey: "pmts.your_secret_key", // required
  projectId: "your_project_id", // required
  baseUrl: "https://custom-api.com/api", // optional, override core API
  edgeUrl: "https://custom-edge.com", // optional, override edge gateway
});

Read operations (checkStatus, customers.*, health) are routed through the edge gateway for caching and resilience. Write operations (createCheckout) go directly to the core API.

Error Handling

import {
  PaymintsError,
  PaymintsInitError,
  PaymintsNetworkError,
  PaymintsValidationError,
} from "@synko-lab/paymints-node";

try {
  await paymints.customers.getById("invalid_id");
} catch (error) {
  if (error instanceof PaymintsNetworkError) {
    console.log("Status:", error.statusCode);
  }
}

API Reference

PaymintsBackend

| Resource | Methods | |----------|---------| | customers | list(), getById(), getByEmail(), exists() | | subscriptions | checkStatus(), createCheckout() | | health | check() |

Types

All types are re-exported from @synko-lab/paymints-core:

• BackendConfig
• Customer, CustomerListParams, PaginatedCustomerResponse
• SubscriptionCheckResponse, CheckSubscriptionParams
• CreateSubscriptionCheckoutParams, CheckoutResponse
• ProjectHealthResponse, PaginationMeta

License

MIT