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

> Merchant invoice APIs (SDK contract): list, retrieve, status, totals, and verification helpers.

## Overview

This page documents the merchant invoice contract used by `pepay`.

## Authentication

Merchant invoice APIs accept either:

* `x-api-key: <merchant_api_key>`, or
* `Authorization: Bearer <jwt>`

## Request

Endpoints (SDK-supported):

* `POST /api/v1/invoices` (create)
* `GET /api/v1/invoices` (list)
* `GET /api/v1/invoices/customer/{customerId}` (list by customer)
* `GET /api/v1/invoices/{invoiceId}` (retrieve)
* `GET /api/v1/invoices/{invoiceId}/status` (status)
* `GET /api/v1/invoices/totals` (totals)

Payor/session helpers (browser-safe auth):

* `GET /api/v1/payments/payment-status`
* `POST /api/v1/invoice/{invoiceId}/verify`
* `GET /api/v1/invoice/{invoiceId}/verify`

Playground (interactive reference):

* [Create an invoice](/api-spec/endpoints/invoices-create)
* [List invoices](/api-spec/endpoints/invoices-list)
* [Retrieve an invoice](/api-spec/endpoints/invoices-retrieve)
* [Get invoice status](/api-spec/endpoints/invoices-status)

Example (create invoice):

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/v1/invoices" \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: 123e4567-e89b-42d3-a456-556642440000" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":49.99,"description":"Starter plan","expires_in":43200000}'
```

Notes:

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

## Response

Example response (create):

```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/403` missing/invalid auth
* `400` invalid invoice payload
* `429` rate limits

Example (invalid payload):

```json theme={null}
{
  "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "Invalid request data" }
}
```

## Examples

Pagination + status semantics:

* List endpoints use cursor pagination (see [Pagination](/api-spec/pagination)).
* Common status fields:
  * Invoice status: `unpaid`, `underpaid`, `paid`, `expired`, `canceled`
  * Payment receipt status: `pending`, `underpaid`, `confirmed`, `manual_retry`
  * Settlement status (merchant-safe): `pending`, `processing`, `manual`, `failed`, `settled`

Next: [Events](/api-spec/merchant/events)