> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pepay SDK Overview

> Install, configure, and use the Pepay JavaScript/TypeScript SDK.

## 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)

```ts theme={null}
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

```json theme={null}
{
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_url": "https://<payment-iframe-host>/pay?session=pst_...&signature=sig_...",
  "expires_at": 1766322000,
  "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`)
* SDK errors include the API `code` and `message` so you can map to user-friendly copy.

## Examples

Poll invoice status until it reaches a terminal state:

```ts theme={null}
const final = await pepay.invoices.waitForStatus(invoice.invoice_id, { timeoutMs: 5 * 60 * 1000 });
console.log(final.invoice.status);
```

Next: [Install](/sdk/install)