> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lipafy.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lipafy.xyz/_mcp/server.

# API Conventions & Standards

> Authentication, base URLs, HTTP headers, rate limits, and standard JSON error response structures.

The Lipafy API is organized around RESTful principles. All request and response bodies use JSON format with UTF-8 encoding.

---

## 🌐 Base URLs

* **Production:** `https://api.lipafy.xyz/v1`
* **Remote MCP Server:** `https://api.lipafy.xyz/mcp`

---

## 🔑 Authentication

All API requests must include your workspace API token in the `Authorization` header using Bearer format:

```bash
Authorization: Bearer lip_live_your_api_key_here
```

---

## 📑 Required Headers

| Header            | Description                                    |             Required?            |
| :---------------- | :--------------------------------------------- | :------------------------------: |
| `Authorization`   | `Bearer <LIPAFY_API_KEY>`                      |              **Yes**             |
| `Content-Type`    | `application/json`                             | **Yes** (for POST / PUT / PATCH) |
| `Idempotency-Key` | Unique UUID or client string (e.g. `uuidv4()`) |  **Yes** (for payment mutations) |

---

## 🛑 Standard Error Response Format

When a request fails, Lipafy returns an RFC 7807 compliant error object:

```json
{
  "error": {
    "code": "INSUFFICIENT_AVAILABLE_BALANCE",
    "message": "Available balance of KES 1,200.00 is insufficient for requested total debit of KES 3,000.00 (Amount: KES 3,000.00, Fee: KES 0.00).",
    "status": 402,
    "details": {
      "available_minor": "120000",
      "requested_minor": "300000",
      "active_holds_minor": "50000"
    },
    "request_id": "req_81f0923ba401"
  }
}
```

---

## ⏱️ Rate Limits & Idempotency

* **Standard Tier:** 120 requests per minute per IP / API key.
* **Burst Limit:** Up to 30 concurrent payment intent creation requests.
* **Idempotency Key:** Required on all mutating requests. Replaying an identical key returns the original cached response; changing payment material with the same key returns HTTP `409 Conflict`.
* When rate limits are exceeded, the API responds with HTTP `429 Too Many Requests` and a `Retry-After: <seconds>` header.