WordPress integration

This guide walks through adding the Donations Embed to any WordPress page or post. It works with the Block editor (Gutenberg, the default since WordPress 5.0) and the Classic editor (still supported via the Classic Editor plugin). It works on WordPress.com sites that allow custom HTML and on every self-hosted WordPress.org install.

The embed renders inside Shadow DOM, so your theme's styles will not interfere with the donor flow.

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 WordPress site - sandbox).
4. Copy the publishable key (starts with pk_test_).

You do not need a secret key for a basic embed integration; copy that only if you also plan to call the server SDK from a WordPress backend plugin.

Step 2: Add the embed to a page (Block editor)

1. Open the page or post in the editor.
2. Click the + button to add a new block, then choose Custom HTML (under "Widgets").
3. Paste the snippet below. Replace pk_test_REPLACE_ME with your publishable key.

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

1. Click Preview to see the rendered embed.
2. Update or Publish the page.

Step 2 (alternative): Add the embed to a page (Classic editor)

1. Open the page or post in the editor.
2. Click the Text tab (top right) to switch from Visual to HTML mode.
3. Paste the same snippet at the spot where you want the embed to appear.
4. Click Preview to see the rendered embed.
5. Update or Publish the page.

Step 3: Test the donation flow (sandbox)

1. Open the published page in a browser.
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. Edit the WordPress page.
3. Replace the pk_test_… value in the snippet 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. Update the page.

That is the entire production cutover. 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

Change the render mode

Inline (the default) renders the flow directly on the page. Switch to a launcher button that opens a centred modal:

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

Or a side drawer that slides in from the right:

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

Constrain to a specific fund

If you want the page to give only to one fund (for example, a building campaign page that should not accept gifts to anything else):

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

The fund picker is hidden when only one fund is available.

Change the theme

Pick one of the four built-in presets — modern (default), minimal, classic, or playful:

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

For per-organisation theming (logo, colours, fonts) without editing every page, configure the theme JSON in the Hub under Donations Embed → Theme.

The full attribute reference, including every customisation option, is in Browser Embed.

Common pitfalls

Note: The embed does not render after I save the page. Open your browser's developer tools and check the Console tab. The most common causes are: (1) a security plugin (Wordfence, iThemes Security) that strips <script> tags from posts — disable the strip rule for that page; (2) a caching plugin (W3 Total Cache, WP Super Cache) serving an old copy without the snippet — purge cache for the page; (3) the publishable key is mistyped.

Note: The script tag disappears every time I save. WordPress' built-in HTML sanitiser strips unknown tags from non-administrator users. If you are signed in as an administrator and the snippet still gets stripped, you have a security plugin doing it. Allowlist <flock-donate> and the <script> tag in your security plugin's content filter.

Note: The snippet renders, but I see "Failed to load embed". Your hosting's Web Application Firewall (WAF) may be blocking the script load from payments.1stflock.com (live mode) or sandbox.payments.1stflock.com (sandbox mode). Allowlist whichever host your snippet uses in your WAF rules.

Note: My theme's styles are colliding with the embed. They cannot be — the embed renders inside Shadow DOM, which is isolated from your theme's CSS. If something looks off, it is the embed's own styling. Configure the theme JSON in the Hub or set CSS custom properties on the <flock-donate> element directly. See Browser Embed → Theming and brand.

Note: The donation appears in the Hub, but my page did not show a success screen. You probably refreshed the page or navigated away after submitting payment. The donation completed server-side; the success screen renders only as long as the page stays open. To redirect to a custom thank-you page, set success-mode="redirect" and success-url="/thank-you".

Next steps

• Try other render modes — see Browser Embed → Render modes.
• Receive donation events on your server — see Webhooks.
• Check the Compliance & Security page for the CSP recipe and customer obligations.