API Conventions & Standards

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:

$
Authorization: Bearer lip_live_your_api_key_here

📑 Required Headers

🛑 Standard Error Response Format

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

1
{
2
  "error": {
3
    "code": "INSUFFICIENT_AVAILABLE_BALANCE",
4
    "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).",
5
    "status": 402,
6
    "details": {
7
      "available_minor": "120000",
8
      "requested_minor": "300000",
9
      "active_holds_minor": "50000"
10
    },
11
    "request_id": "req_81f0923ba401"
12
  }
13
}

⏱️ 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.