How to use the LimaoPay REST API

Short answer

LimaoPay exposes a REST API at /api/v1/ authenticated via API key in the Authorization: Bearer lk_live_... header. Use it to query orders, subscriptions, and replay events.

When to use API vs webhooks

• Webhooks (push): real-time notification. Use to react to events (unlock access on payment).
• REST API (pull): on-demand query. Use to check state (re-sync on startup, recover lost event, show status to user in your app).

Combine both: webhooks to react, REST API to query and as fallback.

Step 1 — Create the API key

1. Go to Dashboard → Developers → API Keys
2. Click New key
3. Pick the mode (live or test) using the global toggle
4. Give it a name (e.g., "Production server")
5. Optional: add IP allowlist (CIDR comma-separated). Ex: 203.0.113.5/32 allows only that IP. Empty = any IP.
6. Click Create API key

The key (lk_live_... or lk_test_...) is shown once. Save it as an env var.

Step 2 — Make requests

All routes require the Authorization: Bearer <key> header.

curl https://api.limaopay.app/api/v1/orders \
  -H "Authorization: Bearer lk_live_a3f9b2c4..."

Endpoints

List orders

GET /api/v1/orders?email=john@example.com&status=paid&limit=25

Filters: email, external_customer_id, status, since (ISO date), limit (default 25, max 100), cursor (pagination).

Get specific order

GET /api/v1/orders/:id

Query a customer's subscriptions

By email:

GET /api/v1/customers/john%40example.com/subscriptions

By external_customer_id (if you attached metadata at checkout):

GET /api/v1/customers/by-external-id/user_123/subscriptions

Get specific subscription

GET /api/v1/subscriptions/:id

Event replay (last 30 days)

GET /api/v1/events?event_type=order.paid&since=2026-05-01

Useful to recover events your webhook missed (e.g., server was down).

Response format

Stripe-style (snake_case):

{
  "object": "list",
  "data": [
    {
      "id": "ord_abc",
      "object": "order",
      "status": "paid",
      "amount_total": 4900,
      "currency": "brl",
      "buyer_email": "john@example.com",
      "external_customer_id": "user_123",
      "external_metadata": { "plan": "pro" },
      "paid_at": "2026-05-11T14:00:00.000Z",
      "created_at": "2026-05-11T13:55:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Rate limit

Per API key:

Exceeded? Returns 401 Rate limit exceeded. Implement exponential backoff.

Test vs live mode

• Test keys (lk_test_...) and live keys (lk_live_...) are fully isolated
• Created via the toggle in /developers dashboard
• Use test keys in staging/dev to avoid generating prod traffic

IP allowlist

Restrict the key to specific IPs (CIDR notation). Useful when your server has a fixed IP:

203.0.113.5/32, 198.51.100.0/24

Empty = accepts any IP.

Revocation

Revoke any key at any time from the dashboard. Immediate effect — the next request with that key returns 401.

Best practices

• ✅ Store the key in env vars (never in code)
• ✅ Create separate keys per environment (one test, one live, one per service)
• ✅ Use IP allowlist when the server has a fixed IP
• ✅ Revoke compromised keys immediately
• ✅ Rotate keys periodically (create new → update app → revoke old)
• ❌ Never use the key in frontend / browser
• ❌ Never commit the key to git
• ❌ Never share via chat/email