Skip to main content

​
Overview

Pepay SDK (pepay) is the recommended way to integrate Pepay from Node.js and modern browsers. Why use the SDK:
  • Typed: TypeScript-first exports with predictable shapes.
  • Safe-by-default: browser runtime blocks server API keys unless explicitly allowed.
  • Practical: built-in idempotency keys and retry behavior for common failure modes.

​
Authentication

Choose the auth mode that matches your surface area:
  • Merchant server: apiKey → x-api-key
  • Commerce server: commerceApiKey → x-commerce-api-key
  • Browser/payor: sessionToken + signature → x-session-token + x-signature
  • WebSockets in browser/mobile: mint a ws_token server-to-server

​
Request

​
Create an invoice (merchant/server)

import { Pepay } from 'pepay';

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

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

​
Response

{
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_url": "https://<payment-iframe-host>/pay?session=pst_...&signature=sig_...",
  "expires_at": "2025-12-21T13:00:00.000Z",
  "session_token": "pst_...",
  "signature": "sig_...",
  "payment_session_headers": {
    "x-session-token": "pst_...",
    "x-signature": "sig_..."
  }
}

​
Errors

  • 401 missing/invalid auth headers
  • 409 idempotency conflicts on write requests (retry with the same Idempotency-Key)
  • 429 rate limits (respect Retry-After)

​
Examples

Poll invoice status until it reaches a terminal state: 
const final = await pepay.invoices.waitForStatus(invoice.invoice_id, { timeoutMs: 5 * 60 * 1000 });
console.log(final.invoice.status);
Next: Install