Developer Documentation

Overview

The Lions Club of Ragama Legends provides APIs and integration tools for approved partners. All API endpoints are served from:

https://lionsclubofragamalegends.lk

Currently available integrations:

• • Partner Payment Gateway — Redirect-based donation flow for embedding donations on your site
• • Projects API — JSON endpoint for listing upcoming and completed community projects

New to our APIs? Start with the Quick Start Guide below.

Quick Start Guide

Follow these steps to integrate with our platform. The entire process typically takes under 30 minutes.

Step 1: Request Partner Access

Email admin@lionsclubofragamalegends.lk with:

• • Your organisation name and website URL
• • Which integration you need (Payment Gateway, Projects API, or both)
• • The exact origin domains that will make requests (e.g. https://yoursite.com)

We will register your partner ID and issue an API key within 1–2 business days.

Step 2: Test Unauthenticated Access

Before receiving your API key, you can test the Projects API immediately with unauthenticated requests (30 req/min limit):

curl https://lionsclubofragamalegends.lk/api/v1/projects

If you receive a JSON response with upcoming and completed arrays, the API is working correctly.

Step 3: Authenticate with Your API Key

Once you receive your API key, include it in the X-API-Key header:

curl -H "X-API-Key: YOUR_KEY_HERE" \
  https://lionsclubofragamalegends.lk/api/v1/projects

Step 4: Integrate into Your Application

Choose your integration — see the detailed sections below:

• • Partner Payment Gateway — Add a donate button to your site
• • Projects API — Display community projects on your site

Step 5: Go Live

Before going live, verify your integration against the Integration Checklist below to ensure everything is production-ready.

Authentication

API endpoints support optional authentication via the X-API-Key header. An API key gives you a higher rate limit (120 requests/min vs 30 requests/min for unauthenticated requests).

X-API-Key: your-api-key

If an invalid API key is provided, the request will be rejected with a 401 Unauthorized response — it will not silently fall back to the public tier.

To request an API key, contact us at admin@lionsclubofragamalegends.lk.

Rate Limiting

All API endpoints enforce per-IP rate limiting. Limits depend on whether the request is authenticated.

Rate limit information is included in response headers:

• • X-RateLimit-Limit — Maximum requests allowed in the window
• • X-RateLimit-Remaining — Requests remaining in the current window
• • Retry-After — Seconds to wait before retrying (only on 429 responses)

When the rate limit is exceeded, the API returns 429 Too Many Requests:

{ "error": "Too many requests" }

Error Responses

All error responses return a JSON body with the following format:

{ "error": "description" }

Partner Payment Gateway

The Partner Payment Gateway allows approved partners to redirect users to our donation page. We support two integration modes:

• • Simple Link — Just pass partner + returnUrl. We show a donation form where the donor enters their amount.
• • Full Params — Pass all parameters (amount, currency, partner, returnUrl). The donor is redirected directly to the payment gateway.

After payment, the user is redirected back to your site with the transaction result.

How It Works

Simple Link (recommended for static sites):

1. User clicks "Donate" on your site
2. Browser redirects to https://lionsclubofragamalegends.lk/donate/partner?partner=YOUR_ID&returnUrl=...
3. User sees a branded donation form and enters their amount
4. User clicks "Proceed to Payment"
5. Our server creates a payment session
6. User is redirected to CyberSource secure payment page
7. User completes (or cancels) the payment
8. Our server redirects the user back to your returnUrl with status params

Full Params (for sites with dynamic amounts):

1. User clicks "Donate" on your site
2. Browser redirects to https://lionsclubofragamalegends.lk/donate/partner?amount=1000&partner=YOUR_ID&currency=LKR&returnUrl=...
3. Our server validates the request and creates a payment session immediately
4. User is redirected to CyberSource secure payment page
5. User completes (or cancels) the payment
6. CyberSource sends the result to our server
7. Our server redirects the user back to your returnUrl with status params

Tutorial: Add a Donate Button

Option A: Simple Link (easiest — no coding needed). The donor will enter their amount on our form:

<a href="https://lionsclubofragamalegends.lk/donate/partner?partner=YOUR_PARTNER_ID&returnUrl=https://yoursite.com/thank-you">
  Donate Now
</a>

Option B: Fixed Amount Link — Pre-fill the amount so the donor goes directly to payment:

<a href="https://lionsclubofragamalegends.lk/donate/partner?amount=1000&partner=YOUR_PARTNER_ID&currency=LKR&returnUrl=https://yoursite.com/thank-you">
  Donate LKR 1,000
</a>

Option C: Dynamic Amount (JavaScript) — for sites with a custom amount input:

function donate(amount) {
  const params = new URLSearchParams({
    amount: amount.toString(),
    partner: 'YOUR_PARTNER_ID',
    currency: 'LKR',
    returnUrl: 'https://yoursite.com/donation-complete',
  });
  window.location.href =
    `https://lionsclubofragamalegends.lk/donate/partner?${params}`;
}

Handle the return callback — On your returnUrl page, read the query parameters to show the result:

// On your thank-you / donation-complete page
const params = new URLSearchParams(window.location.search);
const status  = params.get('status');   // 'success' | 'failed' | 'cancelled' | 'error'
const ref     = params.get('ref');      // Payment reference number
const amount  = params.get('amount');   // Transaction amount
const message = params.get('message');  // Human-readable result

if (status === 'success') {
  showMessage(`Thank you! Payment ${ref} of LKR ${amount} received.`);
} else {
  showMessage(`Payment ${status}: ${message}`);
}

URL: https://lionsclubofragamalegends.lk/donate/partner
Method: Browser redirect (link / anchor tag)

Query Parameters

* If amount and currency are omitted, a branded donation form is shown where the donor enters their amount. If provided, the donor is redirected directly to the payment gateway.

Return Callback Parameters

After payment, these parameters are appended to your returnUrl as query parameters:

Security Notes

• • The returnUrl must use HTTPS and must match one of your registered origin domains
• • Always check the valid parameter (1 = signature verified) before trusting payment status
• • Partner payment sessions are rate-limited to 10 requests per minute per partner+IP

Projects API

Retrieve upcoming and completed community projects in JSON format. This is ideal for displaying our projects on your own website or building dashboards.

Endpoint: GET /api/v1/projects
Base URL: https://lionsclubofragamalegends.lk

Tutorial: Display Projects on Your Site

1. Fetch the data — Make a GET request to the projects endpoint:

const response = await fetch(
  'https://lionsclubofragamalegends.lk/api/v1/projects',
  { headers: { 'X-API-Key': 'YOUR_KEY_HERE' } }
);

if (!response.ok) {
  throw new Error(`API error: ${response.status}`);
}

const { upcoming, completed } = await response.json();

2. Render the projects — Loop through the arrays and display them:

// React example
function ProjectList({ projects }) {
  return (
    <ul>
      {projects.map(project => (
        <li key={project.title}>
          <h3>{project.title}</h3>
          <p>{project.description}</p>
          <span>{project.formattedDate}</span>
          {project.imageUrl && (
            <img src={project.imageUrl} alt={project.title} />
          )}
        </li>
      ))}
    </ul>
  );
}

3. Handle errors gracefully — Check for rate limits and display a fallback:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  console.log(`Rate limited. Retry after ${retryAfter}s`);
  // Show cached data or a friendly message
}

if (response.status === 401) {
  console.error('Invalid API key — check your X-API-Key header');
}

4. Using curl — For quick testing from the command line:

# Without API key (public tier - 30 req/min)
curl https://lionsclubofragamalegends.lk/api/v1/projects

# With API key (authenticated tier - 120 req/min)
curl -H "X-API-Key: YOUR_KEY_HERE" \
  https://lionsclubofragamalegends.lk/api/v1/projects

Request Headers

Response Schema

{
  "upcoming": [
    {
      "title": "Community Health Drive",
      "description": "Free medical screening...",
      "date": "2026-04-15",
      "imageUrl": "https://drive.google.com/thumbnail?id=...",
      "formattedDate": "Planned on April 15th",
      "isUpcoming": true
    }
  ],
  "completed": [...]
}

Project Fields

Cache Behaviour

Responses are cached at the CDN for 5 minutes. Stale content may be served for up to 1 hour while the CDN revalidates in the background. Plan your polling interval accordingly — there is no benefit to calling more frequently than once every 5 minutes.

Integration Checklist

Before going live, verify each item in the checklist below. This ensures your integration is production-ready and follows best practices.

General

• ☐ Partner ID has been issued and confirmed by our team
• ☐ API key is stored securely (environment variable, secret manager — never in client-side code)
• ☐ Error handling is implemented for 401, 429, and 500 responses
• ☐ Rate limit headers (X-RateLimit-Remaining, Retry-After) are respected

Payment Gateway

• ☐ Redirect URL uses HTTPS with your registered origin domain
• ☐ returnUrl points to a dedicated callback page on your site
• ☐ Callback page reads and displays status, ref, amount, and message params
• ☐ The valid param is checked before trusting payment status (1 = verified)
• ☐ Cancelled and failed states are handled with a user-friendly message

Projects API

• ☐ Requests include the X-API-Key header (or handled gracefully without)
• ☐ Polling interval is ≥ 5 minutes (CDN cache window)
• ☐ Empty upcoming/completed arrays are handled in the UI
• ☐ Image URLs are loaded with appropriate alt text

Best Practices for Partners

Follow these guidelines to provide a safe, transparent, and reliable experience for your users when integrating with our donation platform.

Transparency & Disclosure

• • Clearly disclose on your site that donations are processed by and go to the Lions Club of Ragama Legends
• • Display the donation amount prominently before the user clicks the donate button
• • Inform donors that their bank statement will show a charge from Lions Club of Ragama Legends — not from your organisation
• • Do not misrepresent the donation as payment for goods or services

Security

• • Always use HTTPS for your returnUrl — HTTP URLs will be rejected
• • Never expose your API key in client-side code (HTML, JavaScript, mobile apps)
• • Always verify the valid parameter (1 = signature verified) in callback responses before updating your records
• • Implement CSRF protection on your callback/return page to prevent replay attacks
• • Register only the exact origin domains you need — avoid wildcards or broad patterns

Error Handling & User Experience

• • Handle all callback statuses: success, failed, cancelled, and error
• • Show user-friendly messages — do not display raw error codes or transaction IDs
• • Provide a "Try Again" option for failed or cancelled payments
• • Log transaction reference numbers for support and dispute resolution
• • Implement exponential backoff when retrying failed API calls

Performance & Reliability

• • Cache Projects API responses on your end — data refreshes every 5 minutes at most
• • Respect rate limit headers (X-RateLimit-Remaining, Retry-After) to avoid 429 errors
• • Use timeouts on HTTP requests — do not let API calls hang indefinitely
• • Have a fallback UI when the Projects API is temporarily unavailable

Compliance

• • Do not store, process, or transmit cardholder data — our payment gateway handles all card processing securely
• • Include a privacy notice informing donors how their name and email (if provided) will be used
• • If collecting donor information on your end, ensure your privacy policy covers the data sharing with Lions Club
• • For donations above LKR 50,000, encourage donors to provide their name and email for receipt purposes

Support & Contact

We're here to help you integrate successfully.