@1st-flock/donations-embed

Embeddable browser donation flow for 1st Flock — ships a single <flock-donate> web component that any host site can drop in to accept one-time and recurring gifts. Inline, modal, or drawer render modes; themeable; framework-agnostic.

Install

npm install @1st-flock/donations-embed
# or
pnpm add @1st-flock/donations-embed
# or
yarn add @1st-flock/donations-embed

Quickstart

CDN (any HTML page)

The fastest path to a working donor flow — no build step, no bundler.

<flock-donate
  publishable-key="pk_test_8xK2zQ9m2nP4rT5vX7yZ"
  mode="inline"
></flock-donate>
<script type="module" src="https://sandbox.payments.1stflock.com/v1/flock-donate.js"></script>

Open the page, walk the donor flow, and pay with sandbox card 4111 1111 1111 1111, exp 10/29, CVV 123. You'll see a success screen with a confirmation ID like don_8a1b9c4d. The donation appears in your 1st Flock hub within seconds, marked with a TEST badge — no real money moved.

When you go live, swap the script src to https://payments.1stflock.com/v1/flock-donate.js and your pk_test_… key for a pk_live_… key. The SDK enforces the pairing — loading the live host with a pk_test_… key (or vice versa) throws on mount.

Bundler (TypeScript / framework)

import "@1st-flock/donations-embed";

That single side-effect import registers <flock-donate> (and every dependent step / portal element) on window.customElements. Then use it anywhere in your DOM:

<flock-donate publishable-key="pk_test_8xK2zQ9m2nP4rT5vX7yZ"></flock-donate>

For React, prefer the dedicated wrapper @1st-flock/donations-embed-react — it surfaces the same surface as React props + typed event handlers.

Configuration

The embed needs one thing to render: a publishable key (pk_live_… or pk_test_…).

Generate keys in the 1st Flock account portal under Donations Setup → Embed Keys (full guide). Two key types exist:

• Publishable (pk_live_…, pk_test_…) — safe to ship to a browser. The embed authenticates with this. Scoped to an origin allowlist so a leaked publishable key cannot be used from a domain you do not control.
• Secret (sk_live_…, sk_test_…) — server-side only. Used by the server SDKs and webhook signing. Never paste a secret key into HTML, into a React component, or anywhere that ships to a browser.

The embed reads its allowed origins, suggested-amount defaults, fund list, and theme from the platform — you do not need to configure them in the snippet unless you want to override them per-page.

Test mode

Test-mode keys (pk_test_… / sk_test_…) route every request to the sandbox cluster. No real money moves. Cards are simulated; ACH is simulated; webhook deliveries fire normally so you can exercise your handler end-to-end. Donations show up in the hub with a TEST badge and never appear in the production ledger.

The key prefix is the only switch — there is no environment variable, no flag, no separate URL.

Attributes

The minimum to render anything is publishable-key; everything else has a sensible default.

| Attribute | Notes | | --- | --- | | publishable-key (required) | pk_live_… or pk_test_…. | | mode | inline (default), modal, or drawer. | | trigger-label | Launcher button text for modal / drawer. Defaults to Give. | | funds | Comma-list of fund IDs the donor may pick. Empty string hides the picker. | | default-fund | Pre-selected fund ID. | | frequency | Comma-list of allowed frequencies (one-time, weekly, biweekly, monthly, annual). | | default-frequency | Pre-selected frequency. Defaults to one-time. | | cover-fees | true (default) shows the cover-fees toggle; false hides it. | | recurring | true (default) exposes recurring frequencies; false forces one-time. | | theme | modern (default), minimal, classic, or playful. | | success-mode | inline (default), redirect, or callback. | | success-url | Required when success-mode="redirect". | | suggested-amounts | Comma-list of dollar amounts for suggested-amount chips. | | min-amount | Minimum donation, in dollars. Defaults to 1. | | max-amount | Maximum donation, in dollars. | | language | BCP-47 tag. Defaults to en. | | trust-footer | true (default) shows the security footer; false hides it for white-label deployments. | | data-no-analytics | When present (any value) suppresses every host event. |

Detailed reference (each attribute, every default, every interaction) lives at 1stflock.com/developers/donations-embed/.

Common tasks

Change the theme

Pick one of the four built-in presets via the theme attribute, then surgically override individual tokens with CSS custom properties on the host:

<flock-donate
  publishable-key="pk_test_8xK2zQ9m2nP4rT5vX7yZ"
  theme="minimal"
  style="--flock-primary: #0d9488; --flock-radius: 8px;"
></flock-donate>

The full token catalogue is exposed under the --flock- prefix; --flock-primary, --flock-primary-foreground, --flock-surface, --flock-radius, and --flock-font-body cover most brand needs.

React to events

The embed dispatches five CustomEvents on the host element with bubbles: true, composed: true so they escape Shadow DOM and reach window-level listeners:

| Event | When | | --- | --- | | flock-donation-opened | Donor opens the flow (page load for inline, button click for modal/drawer). | | flock-donation-step | Donor advances to the next step. | | flock-donation-complete | The success screen renders. | | flock-donation-failed | The flow fails (declined card, network error, configuration problem). | | flock-donation-closed | Donor leaves the flow without completing. |

<flock-donate publishable-key="pk_test_8xK2zQ9m2nP4rT5vX7yZ"></flock-donate>
<script>
  window.addEventListener("flock-donation-complete", (event) => {
    const { confirmationId, amount, fund } = event.detail;
    console.log(`Donor gave $${amount} to ${fund.name} (${confirmationId})`);
  });
</script>

To opt every event off — for consent-managed analytics platforms — add data-no-analytics to the host element.

Switch render mode

<!-- Inline at the spot where you placed the element. -->
<flock-donate publishable-key="pk_test_8xK2zQ9m2nP4rT5vX7yZ" mode="inline"></flock-donate>

<!-- "Give" button that opens a centred modal overlay. -->
<flock-donate publishable-key="pk_test_8xK2zQ9m2nP4rT5vX7yZ" mode="modal" trigger-label="Give"></flock-donate>

<!-- "Give" button that slides in from the right edge. -->
<flock-donate publishable-key="pk_test_8xK2zQ9m2nP4rT5vX7yZ" mode="drawer"></flock-donate>

Modal and drawer modes lock scroll on the host page while open, trap focus inside the flow, and dismiss on Escape or backdrop click.

Redirect after success

<flock-donate
  publishable-key="pk_test_8xK2zQ9m2nP4rT5vX7yZ"
  success-mode="redirect"
  success-url="/give/thanks"
></flock-donate>

The donor is sent to your URL with ?confirmation_id=… appended.

Full documentation

The full reference — theme token catalogue, every attribute interaction, integration recipes for WordPress / Squarespace / Wix / Next.js, the webhook event taxonomy, and the compliance summary — lives at 1stflock.com/developers/donations-embed/.

Vendor neutrality

This SDK never names the underlying payment processor, bank-link service, or any other third-party vendor in customer-facing strings. Donations carry vendor-neutral identifiers (processor_transaction_id, processor_refund_id, processor_subscription_id); failure messages route through 1st Flock's own taxonomy. The underlying integrations are an implementation detail and may change without notice — your code never has to.

License

MIT — see LICENSE.

Reporting issues

File issues at gitlab.com/1st-flock/donations/-/issues with the label donations-embed.