API reference
Plondo Foundation API
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