Wix integration

This guide adds the Donations Embed to any Wix page using the Embed HTML element. It works with the Wix Editor (the drag-and-drop classic), the Wix Studio editor (the newer Editor X-style), and Velo-by-Wix sites.

Note: Wix's free plan does not allow custom HTML embeds. Confirm you are on a paid plan (Combo, Unlimited, Pro, VIP, or Business) before starting.

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

Step 2: Add an Embed HTML element

1. Open your Wix Editor and navigate to the page where you want the embed.
2. Click Add elements (the + button on the left toolbar).
3. Find Embed Code in the menu, then choose Embed HTML (also labelled Custom Embeds → Embed HTML).
4. The element drops onto your canvas with an "Add Your Code" placeholder.
5. Click Enter Code.
6. Paste the snippet below into the editor. 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 Update.
2. Resize the Embed HTML element on the canvas to roughly 500 px wide × 720 px tall — Wix renders the embed inside a fixed-size iframe, so the container needs enough room for the donor flow. The embed itself is responsive; the constraint is just the Wix iframe.
3. Click Publish (top right).

Step 3: Test the donation flow (sandbox)

1. Open the published site URL in a new browser tab.
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 page in Wix.
3. Open the Embed HTML element and replace the pk_test_… value with the new pk_live_… value.
4. In the same snippet, change the script src from https://sandbox.payments.1stflock.com/v1.js to https://payments.1stflock.com/v1.js.
5. Publish.

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

For a non-disruptive call-to-action that opens the flow in a 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>

In modal mode, you can shrink the Embed HTML element on the Wix canvas down to roughly 200 px × 80 px — only the launcher button needs space; the modal opens at viewport scale.

Constrain to a specific fund

<flock-donate
  publishable-key="pk_test_REPLACE_ME"
  funds="general"
  default-fund="general"
></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.

The full attribute reference is in Browser Embed.

Common pitfalls

Note: The Embed HTML element is missing from the menu. Your Wix plan does not include custom embeds. Upgrade to a paid plan.

Note: The embed renders inside a tiny scrollable iframe. The Embed HTML element renders in a fixed-size iframe whose dimensions you set on the Wix canvas. Resize the element on the canvas to match the embed's natural size (about 500 × 720 px for inline mode, or 200 × 80 px for modal mode where only the launcher button shows).

Note: Modal mode opens the donor flow inside the Wix iframe instead of over the whole page. This is a Wix iframe sandbox limitation — the modal cannot escape the iframe boundary. To get a true full-page modal in Wix, use mode="inline" and let the donor scroll, or contact Wix support to lift the iframe sandbox restrictions for your site (some plans allow this).

Note: The donation appears in the Hub but the success screen is cut off. The Embed HTML element's iframe is too short. Increase the height on the Wix canvas to roughly 720 px so the success screen fits.

Note: My Velo-by-Wix code keeps competing with the embed. The embed is a self-contained web component; do not call any Velo functions against it ($w() selectors do not see inside Shadow DOM). Treat the embed as a black box that emits its own events.

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.