Plain HTML integration

This is the most general integration recipe. If you can save an .html file and serve it from any web server (Apache, Nginx, Caddy, GitHub Pages, Netlify, Cloudflare Pages, Vercel static, S3, your laptop's local file server), you can add the Donations Embed.

There is no build step, no bundler, no transpiler, no framework. Two lines: a custom element and a script tag.

Step 1: Generate a sandbox publishable key

In the 1st Flock Hub:

1. Open Donations Embed → Keys.
2. Click Create key pair.
3. Set environment to Sandbox and name it (e.g. My static site - sandbox).
4. Copy the publishable key (starts with pk_test_).

Step 2: Create the page

Save the following as give.html (or paste it into an existing page). Replace pk_test_REPLACE_ME with your publishable key.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Give to Example Church</title>
  <style>
    body { font-family: system-ui, sans-serif; max-width: 720px; margin: 2rem auto; padding: 0 1rem; }
  </style>
</head>
<body>
  <h1>Give to Example Church</h1>
  <p>Thank you for partnering with us. Every gift goes directly toward our mission.</p>

  <flock-donate
    publishable-key="pk_test_REPLACE_ME"
    mode="inline"
  ></flock-donate>

  <script type="module" src="https://sandbox.payments.1stflock.com/v1.js"></script>
</body>
</html>

That is the entire integration. Open the file in a browser.

Step 3: Test the donation flow (sandbox)

1. Open give.html in a browser (either via your web server or by double-clicking the file).
2. Walk through the donor flow.
3. At the payment step, use these sandbox card details:

See Getting Started → Sandbox testing for the canonical sandbox card details (4111 1111 1111 1111, exp 10/29, CVV 123).

1. Submit. You should see a confirmation screen with an ID like don_8a1b9c4d.
2. Open the Hub's Donations tab — your test donation appears within a few seconds, marked with a TEST badge.

Step 4: Switch to live

When you are ready to take real donations:

1. Generate a live key pair in the Hub (environment set to Live).
2. Open give.html.
3. Replace the pk_test_… value with the new pk_live_… value.
4. Change the script src from https://sandbox.payments.1stflock.com/v1.js to https://payments.1stflock.com/v1.js.
5. Save and re-deploy.

The publishable key and the script host must change together — they are paired.

Cross-mismatch enforcement. If you load the SDK from payments.1stflock.com but supply a pk_test_* key, the SDK throws with: Live SDK cannot use test keys. Load https://sandbox.payments.1stflock.com/v1.js instead. Same in reverse for sandbox.payments.1stflock.com + pk_live_*.

Customisation

Modal launcher button

A non-disruptive call-to-action. The button renders inline; clicking it opens the flow in a centred modal:

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  mode="modal"
  trigger-label="Support our work"
></flock-donate>
<script type="module" src="https://sandbox.payments.1stflock.com/v1.js"></script>

Multiple embeds on one page

You can place several <flock-donate> elements on the same page — for example, a per-fund inline form on a "Give" landing page that lists each fund:

<section>
  <h2>General Fund</h2>
  <flock-donate publishable-key="pk_test_REPLACE_ME" funds="general" default-fund="general"></flock-donate>
</section>

<section>
  <h2>Building Campaign</h2>
  <flock-donate publishable-key="pk_test_REPLACE_ME" funds="building" default-fund="building"></flock-donate>
</section>

<section>
  <h2>Missions</h2>
  <flock-donate publishable-key="pk_test_REPLACE_ME" funds="missions" default-fund="missions"></flock-donate>
</section>

<script type="module" src="https://sandbox.payments.1stflock.com/v1.js"></script>

The script tag only needs to load once per page; all <flock-donate> elements share the same module.

Listen for donation events

To trigger your own analytics or thank-you UI when a donation completes:

<flock-donate publishable-key="pk_test_REPLACE_ME"></flock-donate>
<script type="module" src="https://sandbox.payments.1stflock.com/v1.js"></script>
<script>
  window.addEventListener("flock-donation-complete", (event) => {
    const { confirmationId, amount, fund } = event.detail;
    // Fire your analytics
    if (window.gtag) {
      gtag("event", "donate", {
        transaction_id: confirmationId,
        value: amount,
        currency: "USD",
      });
    }
  });
</script>

The full attribute reference and event catalogue are in Browser Embed.

Common pitfalls

Note: The embed does not render and the browser console shows a CORS error. You probably opened the file directly via file:// rather than serving it from a web server. Some browsers block module scripts when loaded from file://. Run any local web server: python3 -m http.server 8000 from the directory containing give.html, then open http://localhost:8000/give.html.

Note: The embed renders, but my site has a Content Security Policy that blocks it. Add the embed's domains to your CSP. The full recipe is in Compliance & Security.

Note: The success screen redirects but the URL has ?confirmation_id=... appended that I did not configure. That is success-mode="redirect" doing what you asked — the platform appends the confirmation ID so your destination page can render a personalised thank-you. If you do not want the parameter, leave success-mode as the default "inline".

Note: The styling does not match my site. That is by design — the embed renders inside Shadow DOM with its own stylesheet so your site's CSS does not collide with it. To brand the embed, configure the theme JSON in the Hub or set CSS custom properties on the <flock-donate> element. See Browser Embed → Theming and brand.

Next steps

• Read the full Browser Embed reference for every attribute and event.
• Receive donation events on your server — see Webhooks.
• Add a CSP — see Compliance & Security.