Pepay Node.js SDK

Pepay's official JavaScript/TypeScript SDK for merchant, commerce, and payment session APIs. It ships with built-in types, ESM + CommonJS builds, request retries, and webhook helpers.

Documentation

• SDK guides: docs/sdk/overview.md
• API reference: docs/api-reference/introduction.md

Requirements

• Node.js 18+ for server integrations
• Evergreen browsers for client integrations (session token flows)

Installation

npm install pepay

yarn add pepay

pnpm add pepay

Quickstart (server)

import { Pepay } from 'pepay';

const pepay = new Pepay({
  apiKey: process.env.PEPAY_API_KEY,
  baseUrl: 'https://api-beta.pepay.io',
  environment: 'devnet'
});

const invoice = await pepay.invoices.create({
  amount_usd: 49.99,
  description: 'Starter plan'
});

console.log(invoice);

Authentication

Pepay supports multiple auth contexts. Choose the one that matches your surface:

• apiKey -> x-api-key (merchant scope)
• commerceApiKey -> x-commerce-api-key (commerce scope)
• bearerToken -> Authorization: Bearer <jwt> (dashboard/merchant JWT)
• userAccessToken -> User-Authorization: Bearer <token> (commerce user routes)
• sessionToken + signature -> x-session-token + x-signature (payor/session APIs)

Create separate clients or use withAuth() to scope credentials per use case.

Configuration

const pepay = new Pepay({
  apiKey: process.env.PEPAY_API_KEY,
  baseUrl: 'https://api-beta.pepay.io',
  environment: 'devnet',
  timeoutMs: 30_000,
  maxRetries: 2
});

Common options:

• baseUrl and environment select the API host and network context.
• timeoutMs, maxRetries, retryableStatusCodes, and retry tune retry behavior.
• telemetry, appInfo, and userAgent customize request metadata.

Browser usage

Server API keys are blocked by default in browsers. Use session tokens or WS tokens for client apps.

If you must allow server keys in a browser for internal tools, set:

const pepay = new Pepay({ apiKey, allowServerKeysInBrowser: true });

Webhooks

Verify webhook signatures with the built-in helpers:

import { verifyWebhookSignature } from 'pepay';

const result = await verifyWebhookSignature({
  rawBody,
  headers: request.headers,
  secret: process.env.PEPAY_WEBHOOK_SECRET
});

if (!result.valid) {
  throw new Error(`Invalid webhook signature: ${result.reason}`);
}

Pass the raw request body bytes to ensure signature verification succeeds.

WebSocket events

Mint a short-lived WS token server-side, then connect:

const token = await pepay.ws.token.mint({ scope: 'merchant', ttlSeconds: 300 });
const stream = pepay.ws.connectMerchantEvents({ token, types: 'invoice.*' });

stream.on('event', (event) => {
  console.log(event.id, event.type);
});

Retries and timeouts

Pepay retries eligible requests with exponential backoff. Configure:

• maxRetries to control attempts.
• retryMaxElapsedMs to cap total retry time.
• retryableStatusCodes to override default retryable status codes.

Per-request overrides are available via request options, including timeoutMs and idempotencyKey.

Errors

The SDK throws typed errors with API metadata:

• PepayAuthError
• PepayRateLimitError
• PepayValidationError / PepayInvalidCursorError
• PepayHttpError
• PepayCircuitBreakerError
• PepayPollingTimeoutError

Resources

The client exposes typed resources for: invoices, tokens, commerce, events, ws, access, wallets, settlement, paymentSessions, apiKeys, and merchantSettings.

Changelog

See CHANGELOG.md for release notes.

Support

Email [email protected] for access or onboarding help.