> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lipafy.xyz/api-reference/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.

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


## API Docs

- API Reference > Workspaces [Get the authenticated workspace and role](https://docs.lipafy.xyz/api-reference/workspaces/get-current-workspace.md)
- API Reference > Workspaces [Create or resume Personal or Business onboarding](https://docs.lipafy.xyz/api-reference/workspaces/update-onboarding.md)
- API Reference > Beneficiaries [List workspace beneficiaries](https://docs.lipafy.xyz/api-reference/beneficiaries/list-beneficiaries.md)
- API Reference > Beneficiaries [Create a private beneficiary](https://docs.lipafy.xyz/api-reference/beneficiaries/create-beneficiary.md)
- API Reference > Beneficiaries [Disable a beneficiary](https://docs.lipafy.xyz/api-reference/beneficiaries/disable-beneficiary.md)
- API Reference > Beneficiaries [Search Kenyan Paybills, Tills, and Utilities](https://docs.lipafy.xyz/api-reference/beneficiaries/search-paybill-directory.md)
- API Reference > Beneficiaries [List all Kenyan Paybill categories](https://docs.lipafy.xyz/api-reference/beneficiaries/list-paybill-categories.md)
- API Reference > Beneficiaries [Lookup a specific Paybill by slug or business number](https://docs.lipafy.xyz/api-reference/beneficiaries/get-paybill-by-slug-or-number.md)
- API Reference > Payment Intents [List payment intents](https://docs.lipafy.xyz/api-reference/payment-intents/list-payment-intents.md)
- API Reference > Payment Intents [Create a controlled payment intent](https://docs.lipafy.xyz/api-reference/payment-intents/create-payment-intent.md)
- API Reference > Payment Intents [Get payment intent detail, approvals, and executions](https://docs.lipafy.xyz/api-reference/payment-intents/get-payment-intent.md)
- API Reference > Payment Intents [Revalidate and submit an approved payment](https://docs.lipafy.xyz/api-reference/payment-intents/submit-payment-intent.md)
- API Reference > Approvals [List approval requests and immutable snapshots](https://docs.lipafy.xyz/api-reference/approvals/list-approval-requests.md)
- API Reference > Approvals [Approve the exact payment snapshot](https://docs.lipafy.xyz/api-reference/approvals/approve-payment.md)
- API Reference > Approvals [Reject the exact payment snapshot](https://docs.lipafy.xyz/api-reference/approvals/reject-payment.md)
- API Reference > Policies [List workspace spending policies](https://docs.lipafy.xyz/api-reference/policies/list-spending-policies.md)
- API Reference > Policies [Create a spending and approval policy](https://docs.lipafy.xyz/api-reference/policies/create-spending-policy.md)
- API Reference > Webhooks [Reconcile an inbound payment rail event](https://docs.lipafy.xyz/api-reference/webhooks/receive-rail-webhook.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.lipafy.xyz/openapi.json)
- [OpenAPI YAML](https://docs.lipafy.xyz/openapi.yaml)