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

# Invoices

> Create invoices, list with filters, retrieve details, and track status.

## Overview

Invoices are the primary merchant payment object in Pepay.

## Authentication

Merchant invoices typically use:

* `x-api-key` (recommended for server-to-server), or
* `Authorization: Bearer <jwt>` (dashboard session)

## Request

### Create an invoice

```ts theme={null}
const pepay = new Pepay({ apiKey: process.env.PEPAY_API_KEY! });

const invoice = await pepay.invoices.create({
  amount_usd: 49.99,
  description: 'Starter plan',
  expires_in: 12 * 60 * 60 * 1000
});
```

Notes:

* `expires_in` is **milliseconds** (default 12 hours, max 30 days).

### List invoices (cursor pagination + filters)

```ts theme={null}
const list = await pepay.invoices.list({
  limit: 10,
  status: 'paid',
  invoice_type: 'standard',
  environment: 'mainnet'
});
```

### Receipt lookup by payer wallet

```ts theme={null}
const receipts = await pepay.invoices.list({
  payer_wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f6ce3c',
  payer_wallet_network: 'base',
  status: 'paid',
  expand: 'latest_payment'
});
```

### Retrieve invoice details

```ts theme={null}
const invoice = await pepay.invoices.retrieve('inv_123', { expand: 'latest_payment,payments' });
```

### Poll status

```ts theme={null}
const status = await pepay.invoices.status('inv_123');
```

### Wait for terminal status

```ts theme={null}
const final = await pepay.invoices.waitForStatus('inv_123', {
  timeoutMs: 5 * 60 * 1000,
  intervalMs: 2000
});
```

## Response

Create invoice 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_..."
  }
}
```

Invoice status response (polling):

```json theme={null}
{
  "object": "invoice_status",
  "invoice": { "object": "invoice", "id": "550e8400-e29b-41d4-a716-446655440000", "status": "paid" },
  "latest_payment": {
    "object": "invoice_payment",
    "status": "confirmed",
    "settlement_status": "settled",
    "settlement": {
      "summary_status": "settled",
      "stage": "final",
      "merchant_settlement_id": 30,
      "settlement_tx_hash": "0xabc123",
      "network": "bsc",
      "status": "settled"
    }
  }
}
```

## Errors

* `400` invalid invoice params (create) or invalid cursor/filters (list)
* `401` missing/invalid merchant auth headers
* `404` invoice not found (retrieve/status)
* `409` idempotency conflict on create

## Examples

Manual verification (payor/session auth):

```ts theme={null}
await pepay.invoices.manualVerification.trigger(invoiceId, { network: 'base' });
const job = await pepay.invoices.manualVerification.status(invoiceId);
```

Next: [Tokens](/sdk/merchants/tokens)