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

# API Reference Overview

> Complete reference for all LuxCore API endpoints

# API Reference

This section provides detailed documentation for all LuxCore API endpoints.

## Base URL

```
https://api.lux-core.io/api/v1
```

API v2 HMAC payment and balance endpoints are available at:

```
https://api.lux-core.io/api/v2
```

## Authentication

API v1 endpoints require an API key in the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: qp_test_sk_your_api_key" https://api.lux-core.io/api/v1/payments
```

## Endpoints

### Payments

| Method | Endpoint                                | Description                                                        |
| ------ | --------------------------------------- | ------------------------------------------------------------------ |
| `POST` | `/payments`                             | Create a new payment                                               |
| `POST` | `/payments` on the API v2 base URL      | Create a new payment with HMAC authentication for API v2 merchants |
| `GET`  | `/payments/{id}` on the API v2 base URL | Get payment by ID with HMAC authentication for API v2 merchants    |
| `GET`  | `/payments`                             | List payments                                                      |
| `GET`  | `/payments/{id}`                        | Get payment by ID                                                  |
| `POST` | `/payments/{id}/cancel`                 | Cancel a payment                                                   |
| `GET`  | `/payments/methods`                     | Get available payment methods                                      |
| `POST` | `/payments/methods/validate`            | Validate a payment method                                          |

### Webhooks

| Method   | Endpoint                 | Description         |
| -------- | ------------------------ | ------------------- |
| `POST`   | `/webhooks`              | Create a webhook    |
| `GET`    | `/webhooks`              | List webhooks       |
| `GET`    | `/webhooks/{id}`         | Get webhook by ID   |
| `PUT`    | `/webhooks/{id}`         | Update webhook      |
| `DELETE` | `/webhooks/{id}`         | Delete webhook      |
| `POST`   | `/webhooks/{id}/test`    | Send test event     |
| `PUT`    | `/webhooks/{id}/enable`  | Enable webhook      |
| `PUT`    | `/webhooks/{id}/disable` | Disable webhook     |
| `GET`    | `/webhooks/{id}/events`  | Get webhook events  |
| `POST`   | `/webhooks/{id}/retry`   | Retry failed events |

### Balance

| Method | Endpoint                              | Description                                                           |
| ------ | ------------------------------------- | --------------------------------------------------------------------- |
| `GET`  | `/balance`                            | Get balance by currency                                               |
| `GET`  | `/balance` on the API v2 base URL     | Get balance by currency with HMAC authentication for API v2 merchants |
| `GET`  | `/balance/all`                        | Get all balances                                                      |
| `GET`  | `/balance/all` on the API v2 base URL | Get all balances with HMAC authentication for API v2 merchants        |
| `GET`  | `/merchants/{id}/balance`             | Get merchant balance                                                  |
| `GET`  | `/merchants/{id}/balance/all`         | Get all merchant balances                                             |

### Tickets

| Method | Endpoint                                                        | Description                    |
| ------ | --------------------------------------------------------------- | ------------------------------ |
| `POST` | `/tickets`                                                      | Create a support ticket        |
| `GET`  | `/tickets`                                                      | List tickets                   |
| `GET`  | `/tickets/{id}`                                                 | Get ticket details             |
| `POST` | `/tickets/{id}/close`                                           | Close a ticket                 |
| `POST` | `/tickets/{id}/reopen`                                          | Reopen a ticket                |
| `POST` | `/tickets/{id}/comments`                                        | Add a comment                  |
| `GET`  | `/tickets/{id}/comments`                                        | List comments                  |
| `POST` | `/tickets/{id}/upload-url`                                      | Generate attachment upload URL |
| `GET`  | `/tickets/{id}/attachments/{attachmentId}`                      | Download ticket attachment     |
| `GET`  | `/tickets/{id}/comments/{commentId}/attachments/{attachmentId}` | Download comment attachment    |

## Common Parameters

### Pagination

List endpoints support pagination:

| Parameter | Type    | Default | Description                |
| --------- | ------- | ------- | -------------------------- |
| `limit`   | integer | 20      | Results per page (max 100) |
| `offset`  | integer | 0       | Number of results to skip  |

### Filtering

Most list endpoints support filtering by common fields:

| Parameter         | Type     | Description      |
| ----------------- | -------- | ---------------- |
| `status`          | string   | Filter by status |
| `created_at_from` | ISO 8601 | Start date       |
| `created_at_to`   | ISO 8601 | End date         |

## Response Format

### Success Response

```json theme={null}
{
  "success": true,
  "data": { ... },
  "total": 100,
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total_pages": 5
  }
}
```

### Error Response

Business logic errors include `error_code` and `timestamp`:

```json theme={null}
{
  "statusCode": 400,
  "message": "Payment cannot be cancelled in current status: cancelled",
  "error_code": "PAYMENT_ALREADY_PROCESSED",
  "timestamp": "2025-01-28T10:00:00.000Z"
}
```

Validation errors return an array of messages with `error` field:

```json theme={null}
{
  "statusCode": 400,
  "message": [
    "amount must not be less than 1",
    "merchant_reference must be a string"
  ],
  "error": "Bad Request"
}
```

## Rate Limits

| Endpoint Type      | Limit                                   |
| ------------------ | --------------------------------------- |
| Payment creation   | 5000 requests/minute (burst: 500/10sec) |
| Standard endpoints | 100 requests/minute                     |

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1737452100
```

## OpenAPI Specification

Download the OpenAPI specification for use with code generators and API clients:

<Card title="Download OpenAPI Spec" icon="download" href="https://api.lux-core.io/api/v1/openapi.json">
  OpenAPI 3.0 JSON specification
</Card>

## Interactive Documentation

The API also provides interactive documentation:

* **ReDoc**: `https://api.lux-core.io/api/v1/docs`
* **OpenAPI JSON**: `https://api.lux-core.io/api/v1/openapi.json`