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

# API Reference

> Complete reference for the Plexos Pay REST API

## Base URL

```
https://api.plexospay.com
```

## Authentication

All requests require a Bearer token:

```bash theme={null}
Authorization: Bearer sk_test_YOUR_API_KEY
```

## Response Format

Successful responses return the resource directly as JSON. Error responses use this format:

```json theme={null}
{
  "error": {
    "message": "Payment not found",
    "code": "NOT_FOUND"
  }
}
```

## HTTP Status Codes

| Code  | Description                       |
| ----- | --------------------------------- |
| `200` | Success                           |
| `204` | No content                        |
| `400` | Validation error                  |
| `401` | Invalid API key                   |
| `403` | Insufficient permissions          |
| `404` | Resource not found                |
| `409` | Conflict (duplicate, state error) |
| `429` | Rate limit exceeded               |
| `500` | Server error                      |

## Pagination

List endpoints use cursor-based pagination:

```bash theme={null}
GET /v1/payments?limit=20&starting_after=pi_abc123
```

| Parameter        | Description                                |
| ---------------- | ------------------------------------------ |
| `limit`          | Max items per page (1-100, default 20)     |
| `starting_after` | ID of the last item from the previous page |

Responses include:

```json theme={null}
{
  "data": [...],
  "hasMore": true
}
```

## Idempotency

Payment and refund creation support idempotency:

```bash theme={null}
POST /v1/payments
Idempotency-Key: unique-request-id-123
```

If you retry with the same key, you'll get the original response.