Embed a Form

This workflow covers placing a Raise Donation Form on a website your integration controls — a customer’s marketing site, a partner application, an event page. The embed mechanism uses HTML the customer obtains from the Raise admin UI; the partner integration’s role is to deliver that HTML to the right page and handle what happens after the donor completes the form. This is a different workflow from Configure a Donation Form, which covers the partner-side wiring (webhooks, attribution capture) for any form regardless of embed surface. Use this page when the integration actually places a form on a website.

Embed surfaces

There are three distinct embed surfaces, and which one applies depends on what kind of integration you’re building:

Surface	Description	Embed source
Customer’s own website	The customer hosts a marketing site; donations are taken on a “Donate” page that embeds a Raise form.	Embed code from the Raise admin UI, placed directly on the site.
Partner-hosted page in a multi-tenant app	The partner integration provides a page (e.g., a campaign microsite, a donation widget within a partner product) that embeds the customer’s Raise form.	Embed code from the Raise admin UI, retrieved during customer onboarding, served by the partner application.
Custom donation flow with the partner’s own UI	The partner builds a fully custom donation experience and calls `POST /api/Raise/give` directly from a backend.	No Raise form embed — the partner UI handles the entire donor experience.

This page focuses on the first two — embedding the Raise-hosted form. For the third (fully custom flow), see Process a Donation.

The exact embed mechanism (iframe, JavaScript snippet, or other) the Raise admin UI provides is an admin-UI concern, not an API concern. Walk through it with the customer’s Raise administrator when setting up the integration. The patterns on this page apply regardless of the specific embed shape, since all of them deliver HTML/JS to the donor’s browser and POST to /api/Raise/give on submission.

When to use this workflow

Scenario	Approach
Customer wants to add a donation form to their existing website	Use this workflow. The customer’s web team places the embed code; your integration handles the post-donation events.
Partner application provides a donation widget that customers configure	Use this workflow. Your integration retrieves the embed code during customer onboarding and serves it through your application.
Building a fully custom donation form with the partner’s own UI	Skip this workflow. See Process a Donation for the direct `POST /api/Raise/give` flow.
Sending donors to a hosted Raise form via a direct link (no embed)	This is the simplest case — share the form’s landing URL with donors via email, SMS, etc. No embed needed.

The four-step embed workflow

Step 1: customer obtains the embed code

The customer’s Raise administrator opens the form in the admin UI and copies the embed code provided there. This step happens outside the API — your integration doesn’t trigger it. The customer provides the embed code to your integration through whatever onboarding flow you’ve built. Typically this is a settings page in your integration’s UI where the customer pastes the code into a text field:

Settings → Donation Form Embed Code
[                                                                      ]

Validate that the pasted code is non-empty and matches the expected shape (e.g., contains an iframe or script tag pointing at a Raise domain). Don’t try to parse or rewrite the embed code itself — treat it as opaque HTML to be rendered on the target page.

Step 2: render the embed code on the target page

For an integration that hosts the page directly, render the embed code as HTML in the donation page’s body:

HTML

<!DOCTYPE html>
<html>
<head>
  <title>Donate to Wayne Foundation</title>
</head>
<body>
  <h1>Support Our Mission</h1>
  <p>Your gift makes a difference.</p>

  <!-- Begin Raise form embed (from customer's admin UI) -->
  {{ rawEmbedCode }}
  <!-- End Raise form embed -->
</body>
</html>

Three things matter at this point:

HTTPS only. The embed code typically loads resources from Raise over HTTPS; embedding it on an HTTP page will produce mixed-content warnings or block the form entirely in modern browsers. Always serve the embedding page over HTTPS.
No Content Security Policy conflicts. If the embedding page sets a restrictive CSP, allow the Raise origin for frame-src, script-src, and connect-src as appropriate for the embed mechanism. Coordinate the exact directives with the customer if needed.
Don’t wrap or interfere with the embed. The embed code is designed to work as-is. Wrapping the form in another iframe or modifying the embed’s HTML can break the donor experience.

Step 3: capture donation events server-side

When a donor completes the embedded form, the form’s submission flow calls POST /api/Raise/give and creates the Gift in Raise. Your integration learns about the donation through the webhook subscription — not by parsing the embedded form’s UI.

JavaScript

// Webhook handler on your server
app.post('/raise-webhooks', async (req, res) => {
  // Validate signature first — see /raise/webhooks/signature-verification
  if (!validateSignature(req)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  if (event.eventType === GIFT_CREATE_EVENT_TYPE) {
    await processCompletedDonation(event.payload);
  }

  res.status(200).send('OK');
});

This is the same webhook subscription you’d set up for any Raise integration — see Configure a Donation Form. The webhook is the canonical “donation complete” signal. Don’t try to detect form completions through DOM events, postMessage listeners, or other client-side mechanisms — those are unreliable across browsers and embed types. The webhook is the right channel.

Step 4: handle the donor’s return flow

After the form submission completes, the embedded form typically displays a thank-you screen within the embed. The donor stays on your page. Two patterns for what your integration does next:

Pattern A: stay on the embedding page

The simplest pattern — let the form’s built-in thank-you display handle the user experience and let your integration’s server-side webhook handler trigger any background work (thank-you email, CRM sync, etc.). This is the right default when:

The embedding page is a standalone donation page that doesn’t need to do anything user-facing after the donation.
The form’s thank-you display is sufficient on its own.

Pattern B: redirect or display custom content

For more involved flows — multi-step processes, custom thank-you experiences, or integration-specific follow-ups — coordinate with the form’s configuration to redirect or display custom content after submission. The mechanism for this is form-configuration-side (set in the Raise admin UI) — not via API. Coordinate with the customer’s admin team to configure the form’s success behavior. From the partner side, what your integration controls is the destination URL the form redirects to and any logic on that destination page.

JavaScript

// Example: a custom thank-you page that pulls the gift ID from the URL
// (set by the form's post-submission redirect, configured in admin UI)
app.get('/donation-thank-you', async (req, res) => {
  const giftId = req.query.giftId;

  // Look up the gift for display details
  const gift = await fetchGift(giftId);

  res.render('thank-you', {
    donorName: gift.donor?.firstName,
    amount: gift.formattedAmount,
    project: gift.projects[0]?.projectName,
  });
});

The form’s exact post-submission redirect behavior (whether a giftId query parameter is appended, the redirect URL configuration, etc.) is set in the Raise admin UI and not documented in the API spec. Confirm against the live form configuration before relying on specific URL parameters.

Multi-customer embed patterns

For partner integrations that host donation pages for multiple customers, each customer’s embed code needs to be served correctly to their respective pages.

Pattern: per-customer embed code storage

Store the embed code as a per-customer setting:

JavaScript

// Per-customer settings table
const customerSettings = {
  customer_acme: {
    raiseEmbedCode: '<iframe src="..." ></iframe>',
    raiseApiToken: '...',
    raiseWebhookId: 'webhook_123',
  },
  customer_beta: {
    raiseEmbedCode: '<script src="..."></script>',
    raiseApiToken: '...',
    raiseWebhookId: 'webhook_456',
  },
};

// Donation page handler — looks up the right embed code by customer
app.get('/donate/:customerId', async (req, res) => {
  const { customerId } = req.params;
  const settings = customerSettings[customerId];
  if (!settings?.raiseEmbedCode) {
    return res.status(404).send('Donation form not configured');
  }

  res.render('donation-page', {
    embedCode: settings.raiseEmbedCode,
    customerName: settings.displayName,
  });
});

The embed code is opaque HTML/JS — your integration doesn’t need to understand what’s inside it, just to serve it to the right page.

Multiple forms per customer

A single customer often has multiple forms (general giving, monthly sustainers, capital campaign, etc.). Store each form’s embed code separately and let the customer choose which form a specific page uses:

JavaScript

const customerSettings = {
  customer_acme: {
    forms: {
      'general': { id: 1234, embedCode: '...' },
      'monthly': { id: 5678, embedCode: '...' },
      'capital-2025': { id: 9012, embedCode: '...' },
    },
  },
};

app.get('/donate/:customerId/:formKey', async (req, res) => {
  const { customerId, formKey } = req.params;
  const form = customerSettings[customerId]?.forms[formKey];
  if (!form) return res.status(404).send('Form not configured');

  res.render('donation-page', { embedCode: form.embedCode });
});

This produces URLs like /donate/customer_acme/general, /donate/customer_acme/monthly, etc. — clean per-form entry points without each form needing its own bespoke page.

Testing the embed locally

For development, embed the form on a local page that runs over HTTPS. Tools that help:

Tool	Use
ngrok or Cloudflare Tunnel	Expose your local development server over HTTPS with a real certificate.
Test-mode Raise organization	Embed against a customer’s test-mode account so submissions don’t charge real cards.
Browser developer tools	Verify there are no CSP errors, mixed-content warnings, or blocked resources.

A typical local-dev setup:

Start your local server over HTTPS

Use ngrok to expose localhost:3000 over HTTPS at a public URL.

Configure the customer's test-mode form to allow your dev origin

If the form’s embed has origin restrictions, add your ngrok URL to the allowlist temporarily. Coordinate with the customer’s admin if needed.

Use the test-payment-method generator

POST /api/Raise/generate-test-payment-method produces a token usable in test mode. Use this for development submissions.

Subscribe your dev webhook to the test-mode events

Point your webhook subscription’s notificationUrl at your ngrok URL so events from test-mode donations reach your local development server.

Run a test donation through the embedded form

Confirm the donation completes, the webhook arrives, and your post-donation logic fires correctly.

See Local Testing for the webhook-specific testing patterns.

Common embed issues

A few issues come up frequently when embedding Raise forms. Quick references:

Symptom	Likely cause
Form doesn’t load	Embedding page is HTTP, not HTTPS; CSP blocks the embed; browser ad-blocker filtering.
Form loads but submissions fail	Customer’s account is misconfigured (e.g., no payment gateway); test-mode payment method used in non-test environment.
Donation succeeds but webhook doesn’t arrive	Webhook subscription’s `notificationUrl` is wrong; signature validation failing; firewall blocking inbound from Raise’s IPs.
Donor stays on the form’s thank-you instead of returning to your site	Form’s success behavior is configured to stay on Raise — coordinate with admin to change to a redirect.
Embedding multiple forms on the same page causes one to misbehave	Embed codes may not be designed for multi-instance pages — confirm with admin team.

The webhook log endpoints (GET /api/Webhook/{id}/log/list) are particularly useful for investigating “donation succeeded but webhook didn’t arrive” — they show whether Raise attempted delivery and how the receiver responded. See Webhooks Overview.

Where to go next

Configure a Donation Form

The complementary workflow for the partner-side wiring around any form.

Process a Donation

The POST /api/Raise/give flow for fully-custom (non-embedded) donation experiences.

Webhooks Overview

Set up the webhook subscription that delivers donation events to your integration.

Embed a Form on a Website (Recipe)

An end-to-end recipe walking through a complete embed-and-react integration.

Getting Started

Core Concepts

Workflows

Webhooks

Recipes

Best Practices

Embed surfaces

When to use this workflow

The four-step embed workflow

Step 1: customer obtains the embed code

Step 2: render the embed code on the target page

Step 3: capture donation events server-side

Step 4: handle the donor’s return flow

Pattern A: stay on the embedding page

Pattern B: redirect or display custom content

Multi-customer embed patterns

Pattern: per-customer embed code storage

Multiple forms per customer

Testing the embed locally

Common embed issues

Where to go next

Configure a Donation Form

Process a Donation

Webhooks Overview

Embed a Form on a Website (Recipe)

​Embed surfaces

​When to use this workflow

​The four-step embed workflow

​Step 1: customer obtains the embed code

​Step 2: render the embed code on the target page

​Step 3: capture donation events server-side

​Step 4: handle the donor’s return flow

​Pattern A: stay on the embedding page

​Pattern B: redirect or display custom content

​Multi-customer embed patterns

​Pattern: per-customer embed code storage

​Multiple forms per customer

​Testing the embed locally

​Common embed issues

​Where to go next

Configure a Donation Form

Process a Donation

Webhooks Overview

Embed a Form on a Website (Recipe)

Embed surfaces

When to use this workflow

The four-step embed workflow

Step 1: customer obtains the embed code

Step 2: render the embed code on the target page

Step 3: capture donation events server-side

Step 4: handle the donor’s return flow

Pattern A: stay on the embedding page

Pattern B: redirect or display custom content

Multi-customer embed patterns

Pattern: per-customer embed code storage

Multiple forms per customer

Testing the embed locally

Common embed issues

Where to go next