Donations Embed

The Donations Embed lets your nonprofit accept one-time gifts on any website — from a static HTML page to a full React or Next.js app. Drop in a single web component, configure it with one publishable key, and donations flow into your 1st Flock account with full receipt, ledger, and reconciliation pipelines wired up automatically. (Recurring giving is available through your organisation's 1st Flock account experience, where donors can manage their schedules.)

This documentation set covers everything you need to integrate, operate, and remain compliant: a 5-minute Quickstart, the full attribute reference for the browser embed, server SDKs in three languages, signed webhooks with replay protection, PCI SAQ A scope, and a per-platform integration cookbook for the most common host platforms.

What you get

• Browser embed — a single web component (<flock-donate>) plus a React wrapper (<FlockDonate>). Inline, modal, or drawer render modes. Attributes for theming, fund picking, success behaviour, and analytics opt-out.
• Server SDKs — typed clients for TypeScript / Node, Python, and Go with identical surfaces: list donations, fetch a donation, refund, list recurring schedules, cancel a schedule, fire a synthetic webhook for integration testing.
• Signed webhooks — nine event types, HMAC-SHA256 signatures with a 5-minute replay window, at-least-once delivery, exponential backoff over eight attempts, and a constant-time verifier in every SDK.
• Sandbox mode — pk_test_… / sk_test_… keys route every call to the sandbox cluster; no real money moves. Same wire format, same SDK code path, same webhook events.
• PCI SAQ A scope — donor card data is tokenised inside an isolated iframe before it ever touches your code. Your servers never see a PAN.

Where to start

• New to the embed? Start with Getting Started for a copy-paste-ready 5-minute walkthrough.
• Building a server-side integration? Read Server SDKs and pick the language that matches your stack.
• Writing webhook handlers? Jump straight to Webhooks.
• Need to satisfy your annual PCI questionnaire? See Compliance & Security.
• Adding the embed to WordPress / Squarespace / Wix / Next.js / a plain HTML page? Each host platform has a step-by-step guide under Integration Examples.
• Deep API reference? See API Reference.
• Operations questions (versioning, rate limits, deprecation policy)? See Operations.
• Tracking what changed between releases? See the Changelog.

Conventions used throughout these docs

• pk_test_REPLACE_ME / sk_test_REPLACE_ME are placeholders. Generate real keys in the 1st Flock account portal under Donations Embed → Keys.
• Code blocks with a tabbed header show the same example in multiple languages. Pick one tab — the choice persists across the whole docs site for the rest of your session.
• Sandbox vs Live is determined by the key prefix, not by a separate URL or flag. pk_test_… and sk_test_… always hit the sandbox cluster; pk_live_… and sk_live_… always hit production.
• Vendor-neutral identifiers — the API returns processor_transaction_id, processor_refund_id, and processor_subscription_id. The underlying gateway is an implementation detail and may change without notice.