API reference

Plondo Foundation API

Developer portal

A small REST API for donations, contact, and status. Base URL https://plondofoundation.org. All responses are JSON; all errors use { "error", "code", "message" }. Full machine-readable spec at /openapi.json.

GET/api/health

Service status. No auth.

curl https://plondofoundation.org/api/health

{ "ok": true, "stripe": true, "database": true, "twilio": true, "smtp": true }

GET/api/public-config

Browser-safe configuration. Returns the referrer-restricted Google Maps key used by client-side address autocomplete.

{ "googleMapsApiKey": "..." }

POST/api/create-payment-intent

Create a one-time or recurring monthly donation. Card details are tokenized in the browser with Stripe.js; the server only receives a Stripe paymentMethodId. Amounts are from $10 to $10,000 (1000 to 1,000,000 cents). When /api/public-config returns a turnstileSiteKey, the request needs a Cloudflare Turnstile token from the donation page. Attempts are limited per IP and per email, and donations pause for all callers during a card-testing attack.

Request body

{
  "amount": 5000,                 // integer cents (1000–1000000)
  "type": "One-time",             // or "Monthly"
  "paymentMethodId": "pm_...",    // from stripe.createPaymentMethod
  "turnstileToken": "...",        // when the bot check is on
  "email": "donor@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "company": "",                  // optional
  "phone": "",                    // optional
  "address": "", "city": "", "state": "",
  "postalCode": "", "country": "US"
}

Response

{ "status": "succeeded",           // or "requires_action" / "requires_confirmation"
  "attemptId": "0b6f...",          // uuid
  "clientSecret": "pi_..._secret_...", // only when a browser step is needed
  "paymentIntentId": "pi_...",
  "subscriptionId": "sub_...",     // monthly
  "amount": 5000, "currency": "usd", "type": "One-time" }

The server confirms a one-time gift itself. When clientSecret is present, run stripe.confirmCardPayment(clientSecret), then POST /api/donation-result with { "attemptId" }.

Errors: 402 card_declined (the reason is not given), 403 bot_check_failed, 429 donation_limit, 503 donations_paused.

curl -X POST https://plondofoundation.org/api/create-payment-intent \
  -H "Content-Type: application/json" \
  -d '{"amount":5000,"type":"One-time","paymentMethodId":"pm_123","email":"donor@example.com","firstName":"Ada","lastName":"Lovelace"}'

POST/api/contact

Send the Foundation a message. Protected by rate limiting and a honeypot field.

curl -X POST https://plondofoundation.org/api/contact \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","subject":"Hello","message":"..."}'

{ "ok": true }

Errors

All endpoints return structured JSON errors with an HTTP status that matches:

{ "error": "Invalid amount", "code": "bad_request", "message": "..." }

Authentication

No API key is needed. Donations use a Stripe paymentMethodId created in the browser with Stripe.js.

Rate limits

60 requests per minute per IP on /api/*; 10 per minute on POST /api/create-payment-intent and POST /api/contact. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds) and RateLimit-Policy (for example 60;w=60). Over the limit you get 429 with Retry-After:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
{ "error": "Too Many Requests", "code": "rate_limited", "message": "Rate limit exceeded (60 requests per 60 seconds). Retry after 12 seconds." }

Versioning

Every route above is also served at /api/v1/<name> (for example /api/v1/health). Responses carry API-Version: 1. Breaking changes ship as /api/v2. A deprecated version answers with Deprecation and Sunset headers at least 6 months before removal.

Machine-readable resources

openapi.json · API catalog · llms.txt

Command-line tool

An official CLI wraps this API — plondo-foundation-cli on npm:

npx plondo-foundation-cli health   # check API status
npx plondo-foundation-cli docs     # print developer/docs URLs

Or run it straight from the source repository:

node cli/plondo.js health

OpenAPI spec   Back to developer portal