Embeddable Donation Form

Embedding the Form

The Donately embeddable form is a JavaScript-powered donation form that supports credit cards, ACH bank transfers, PayPal, Apple Pay, Google Pay, recurring donations, custom fields, and more.

Method 1: Simple Script (Recommended)

The easiest way to embed your form. Add a single script tag with your account ID, Stripe key, and form ID. The form configuration is fetched automatically from the Donately API. Works on any page builder that lets your script run in the page itself (Webflow, Squarespace, Drupal, etc.). Not Wix: its HTML block sandboxes pasted markup in a cross-origin frame without allow="payment", which silently removes Apple Pay and Google Pay. Use Method 4 there.

<script
  src="https://cdn.donately.com/core/6.0/donately.min.js"
  data-donately-id="act_ba7d12ab27bb"
  data-stripe-publishable-key="pk_live_xxxx"
  data-donately-form-id="frm_xxxx"
  data-donately-fetch-config="true"
  async="async">
</script>

Method 2: Iframe

Perfect for tools that limit your ability to use JavaScript on your site (e.g., WordPress). The iframe is generated automatically from your form configuration.

<iframe
  src="https://cdn.donately.com/core/6.0/donate-form.html?form_id=frm_xxxx&account_id=act_ba7d12ab27bb&stripe_key=pk_live_xxxx"
  width="100%"
  height="850px"
  frameborder="0"
  allowtransparency="true"
  allow="payment *"
  style="max-width:600px;">
</iframe>

Method 3: Advanced Script

Gives you full control of the embed code. Best for developers with programming experience who want to customize callbacks, handle events, or pass dynamic options.

<div id="dntly-donation-form"></div>
<script src="https://cdn.donately.com/core/6.0/donately.min.js" async="async"></script>
<script>
  dntlyReady("Donately", function(t) {
    Donately.init({
      selector: '#dntly-donation-form',
      options: {
        "donately-id": "act_ba7d12ab27bb",
        "stripe-publishable-key": "pk_live_xxxx",
        "donately-form-id": "frm_xxxx"
      },
      afterFormLoad: function() {},
      afterNavigateHook: function(stepNumber) {},
      onSuccess: function(donation) {},
      onError: function(error) {}
    });
  });
  function dntlyReady(name, callback) {
    window.setTimeout(function() {
      if (window[name]) { callback(window[name]); }
      else { dntlyReady(name, callback); }
    }, 10);
  }
</script>

Method 4: Custom Element

For page builders that refuse to run your script in the page. Wix is the one that matters today: its “HTML Code” element sandboxes whatever you paste into a cross-origin frame with no allow="payment", so Apple Pay and Google Pay cannot run there no matter how the form is embedded. Its separate “Custom Element” widget does put your tag in the published page’s own DOM, but it accepts only a script URL and a tag name, never markup.

donately-element.js registers <donately-donate-form> for exactly that slot. It is a delivery format, not a different technique: the element writes the Method 1 script into itself, with the same loader and the same data-donately-* attributes. Pasting it into an HTML block fails the same way Method 1 does.

<script src="https://cdn.donately.com/core/6.0/donately-element.js" async="async"></script>
<donately-donate-form
  account-id="act_ba7d12ab27bb"
  form-id="frm_xxxx"
  stripe-key="pk_live_xxxx"></donately-donate-form>

On Wix you do not paste that. Add “Embed Code”, then “Custom Element”, and fill in the fields:

Attribute names are the element’s own; it maps them to the data-donately-* names the bundle reads. Any extra data-* attribute is passed through verbatim, so campaign-id and data-donately-campaign-id both work.

Requires a browser with custom element support; the element logs a warning and renders nothing on anything older. See also the step-by-step Wix embedding guide.

Required Options

Donation Options

Amount Configuration

Pass a number for a simple default, or an object for more control:

// Simple default amount
"amount": 50

// Object with full options
"amount": {
  "default": 50,
  "placeholder": 100,
  "disabled": false,
  "required": false
}

Presets Configuration

Pass a comma-separated string for simple presets, or an object for advanced control:

// Simple comma-separated
"presets": "25,50,100,250"

// Advanced object format
"presets": {
  "presets": [
    { "label": "$25", "amount": 25 },
    { "label": "$50", "amount": 50 },
    { "label": "{{currency_symbol}}100", "amount": 100 },
    { "label": "Other Amount", "amount": "", "type": "input" }
  ],
  "fullWidthPresets": true,
  "presetsAsSelect": false
}

Preset Object Properties

Donor Fields

Control which donor information fields are shown on the form. Most fields accept either true to enable with defaults, or a configuration object for more control.

Field Configuration

Fields that accept objects can be passed as true to enable with defaults, or as an object for granular control.

name

// Enable with defaults
"name": true

// With options
"name": { "required": true }

phone

// Enable with defaults (required)
"phone": true

// Enable but optional
"phone": { "required": false }

address

// Enable with defaults (required)
"address": true

// With full options
"address": {
  "required": true,
  "preselect_country": "US",
  "disabled": false
}

Donor Pays Fees

The donor-pays-fees option lets donors opt in to covering transaction fees so the nonprofit receives the full donation amount. This option supports multiple configuration formats depending on how much control you need.

Simple Boolean

Enable with default fee calculations for all payment methods:

"donor-pays-fees": true

Simple Percentage

Apply a single percentage across all payment methods:

"donor-pays-fees": "0.042"

Per-Payment-Method Configuration

For full control, pass an object with fee settings for each payment method:

"donor-pays-fees": {
  "preselected": true,
  "cc": {
    "processor_percent": 0.029,
    "processor_fixed": 0.30,
    "dntly_percent": 0.04,
    "complex_calc": true
  },
  "ach": {
    "processor_percent": 0.008,
    "processor_fixed": 0,
    "processor_cap": 5.00,
    "dntly_percent": 0.04,
    "complex_calc": true
  },
  "paypal": {
    "processor_percent": 0.029,
    "processor_fixed": 0.30,
    "dntly_percent": 0.04
  }
}

Top-Level Properties

Payment Method Properties

Each payment method key (cc, ach, paypal, wallet, cash) accepts these properties:

Common Examples

// Flat 3% fee on credit card donations
"donor-pays-fees": {
  "cc": {
    "processor_percent": 0.03,
    "processor_fixed": 0,
    "dntly_percent": 0,
    "complex_calc": false
  }
}

// Flat $2.50 fee on all donations
"donor-pays-fees": {
  "cc": {
    "processor_percent": 0,
    "processor_fixed": 2.50,
    "dntly_percent": 0,
    "complex_calc": false
  }
}

// ACH with $5 cap
"donor-pays-fees": {
  "ach": {
    "processor_percent": 0.008,
    "processor_fixed": 0,
    "processor_cap": 5.00,
    "dntly_percent": 0.04
  }
}

Recurring Donation Options

Configure how recurring donations are presented to donors.

Using recurring-options (Recommended)

"recurring-options": {
  "frequencies": ["false", "1.month", "3.month", "12.month"],
  "type": "toggle"
}

Available Frequencies

Legacy Options

Payment Methods

Control which payment methods are available on the form.

"payment-options": "cc,wallet,ach,paypal"

Custom Fields

Add custom form fields that are stored as metadata on the donation. Pass as a JSON array.

"custom-fields": [
  {
    "type": "text",
    "label": "Company Name",
    "name": "company_name",
    "required": true
  },
  {
    "type": "select",
    "label": "How did you hear about us?",
    "name": "referral_source",
    "options": ["Google", "Social Media", "Friend", "Event", "Other"]
  },
  {
    "type": "checkbox",
    "label": "Add me to the mailing list",
    "name": "mailing_list"
  },
  {
    "type": "section",
    "label": "Additional Information"
  },
  {
    "type": "hidden",
    "name": "source",
    "value": "website-homepage"
  }
]

Field Types

Styling & Themes

Pre-built Themes

"theme": "clean"

Available themes: clean, minimal, and more.

Custom Theme (CSS Variables)

Override specific CSS variables to match your brand:

"custom-theme": {
  "-PrimaryColor": "#4A90D9",
  "-PrimaryFontFamily": "Helvetica, Arial, sans-serif",
  "-PrimaryFontSize": "16px",
  "-FormBackgroundColor": "#ffffff",
  "-FormOuterPadding": "20px",
  "-FieldBorderColor": "#cccccc",
  "-FieldBorderWidth": "1px",
  "-FieldBackgroundColor": "#fafafa",
  "-FieldFontColor": "#333333",
  "-LabelFontColor": "#555555",
  "-ErrorTextColor": "#dc3545"
}

Available CSS Variables

Custom CSS

For full control, inject custom CSS:

"custom-css": ".dntly-form .dntly-submit-btn { border-radius: 50px; }"

Internationalization

The form supports multiple languages out of the box.

Supported Locales

• en_US — English (US) — default
• es_ES — Spanish
• fr_CA — French (Canadian)
• de_DE — German
• it_IT — Italian
• sv_SE — Swedish
• zh_HK — Chinese (Hong Kong)

Confirmation Screen

Customize what donors see after a successful donation. You can change the thank-you message, enable social sharing, or redirect to an external page.

"confirmation-config": {
  "thank_you_message_header": "Thank you for your {{formatted_amount}} donation!",
  "thank_you_message_subheader": "A receipt has been sent to {{email}}.",
  "display_social_icons": true,
  "social_share_message": "I just donated to {{social_share_account_title}}!",
  "social_share_account_title": "Our Nonprofit",
  "social_share_url": "https://example.org/donate",
  "twitter_hashtags": "donate,giveback"
}

Message Options

Social Sharing Options

Redirect Options

Redirect with Payload Example

When redirect_with_payload is true, the donor is redirected with the complete donation object appended as a query parameter. This includes the donation ID, amount, donor email, subscription details, and metadata.

"confirmation-config": {
  "redirect_url": "https://example.org/thank-you",
  "redirect_with_payload": true
}

Form Navigation

Configure multi-step form navigation to break the form into logical steps. Pass a JSON object with step definitions:

"form-navigation": {
  "steps": [
    {
      "label": "Amount",
      "sections": ["presets", "amount", "donorpaysfees", "recurringgroup"]
    },
    {
      "label": "Payment",
      "sections": ["paymentmethods"]
    },
    {
      "label": "Your Info",
      "sections": ["namegroup", "email", "phone", "addressgroup", "comment"]
    },
    {
      "label": "Review",
      "sections": ["summary", "submit"]
    }
  ]
}

Available Sections

URL Parameter Prefill

You can pre-populate form values by appending query parameters to the donation page URL. This works on hosted Donately pages (pages.donately.com) and on any page where the form is embedded directly (HTTPS required).

There are two types of URL parameters:

• Form Option — Sets a form configuration option (e.g., default amount, campaign, recurring frequency). Uses short parameter names like amount, campaign-id.
• Field Prefill — Directly sets the value of a form input field after the form loads. Uses donately- prefixed parameter names that match the field element IDs (e.g., donately-first-name, donately-email).

Example

https://pages.donately.com/yourorg/form/frm_xxxx?campaign-id=cmp_7ce279325f9e&recurring-frequency=1.month&amount=55

Form Option Parameters

These parameters set form configuration options. Values are validated and only whitelisted parameters are accepted.

Field Prefill Parameters

These parameters directly set the value of form input fields after the form loads. Use the field's element ID as the parameter name.

Example: Multiple Parameters

https://pages.donately.com/yourorg/form/frm_xxxx?amount=100&recurring-frequency=1.month&campaign-id=cmp_xxxx&donately-email=jane@example.com&donately-first-name=Jane&donately-last-name=Doe

Callbacks & Events

Callbacks are passed in the Donately.init() configuration:

Example

Donately.init({
  selector: '#my-form',
  options: { ... },
  onSuccess: function(donation) {
    // Redirect to a thank-you page
    window.location.href = '/thank-you?amount=' + donation.amount_in_cents;
  },
  onError: function(error) {
    console.error('Donation failed:', error.message);
  }
});

3rd Party & Analytics

The form supports built-in tracking for Google Analytics and Facebook Pixel, as well as integrations with third-party services.

Attribution & UTM Tracking

Donately records the page URL the form was loaded on, and the UTM parameters reported in the dashboard are parsed from that URL at the moment the form loads. If a visitor clicks an ad today and donates next week from a bookmark, the URL carries no parameters and the UTM columns are empty.

To attribute delayed conversions, store the first-touch parameters in the browser and feed them into hidden fields on the form. Donately saves any custom field onto the donation record, so the values flow into reporting and exports.

Step 1: Add hidden fields

Declare one hidden field per value you want to keep. See Custom Fields for the full field reference.

"custom-fields": [
  { "type": "hidden", "id": "utm_source" },
  { "type": "hidden", "id": "utm_medium" },
  { "type": "hidden", "id": "utm_campaign" },
  { "type": "hidden", "id": "utm_content" },
  { "type": "hidden", "id": "utm_term" },
  { "type": "hidden", "id": "utm_id" },
  { "type": "hidden", "id": "gclid" },
  { "type": "hidden", "id": "fbclid" }
]

Always set id explicitly. The DOM element id and the meta_data key are both derived from it, and the rules are strict:

Only the first row gives you an id you can target from your own script.

Step 2: Capture first touch

Run this as early as possible on every page that can receive ad traffic, not just the donation page.

(function () {

  var ATTRIBUTION_DAYS = 30;
  var ATTRIBUTION_MS   = ATTRIBUTION_DAYS * 24 * 60 * 60 * 1000;
  var TIMESTAMP_KEY    = "dntly_attr_timestamp";

  var KEYS = [
    "utm_source", "utm_medium", "utm_campaign", "utm_content",
    "utm_term", "utm_id", "gclid", "fbclid"
  ];

  var params = new URLSearchParams(window.location.search);

  function clearAll() {
    KEYS.forEach(function (k) {
      localStorage.removeItem("dntly_attr_" + k);
    });
    localStorage.removeItem(TIMESTAMP_KEY);
  }

  var now      = Date.now();
  var storedAt = parseInt(localStorage.getItem(TIMESTAMP_KEY), 10) || 0;

  if (storedAt && (now - storedAt) > ATTRIBUTION_MS) {
    clearAll();
  }

  var incoming = KEYS.some(function (k) {
    return !!params.get(k);
  });

  // Any marketing parameter present means a new click. Clear the previous
  // set first, or a Google click inherits the fbclid from an earlier Meta one.
  if (incoming) {

    clearAll();

    KEYS.forEach(function (k) {
      var v = params.get(k);
      if (v) {
        localStorage.setItem("dntly_attr_" + k, v);
      }
    });

    localStorage.setItem(TIMESTAMP_KEY, String(now));
  }

})();

Step 3: Populate the fields

The form renders asynchronously, so poll briefly rather than assuming the fields exist at load.

window.addEventListener("load", function () {

  var KEYS = [
    "utm_source", "utm_medium", "utm_campaign", "utm_content",
    "utm_term", "utm_id", "gclid", "fbclid"
  ];

  var attempts = 0;

  var interval = setInterval(function () {

    KEYS.forEach(function (k) {
      var field = document.getElementById(k);
      if (field) {
        field.value = localStorage.getItem("dntly_attr_" + k) || "";
      }
    });

    if (++attempts >= 20) {
      clearInterval(interval);
    }

  }, 500);

});

Where the values land

Each hidden field is stored on the donation's meta_data, keyed by the field id, and is available through the API, exports, and as a column in the Donations table.

{
  "utm_source": "meta",
  "utm_medium": "paid_social",
  "utm_campaign": "spring_appeal",
  "utm_content": "120251589127400551"
}

These are separate from Donately's own UTM columns, which continue to read from the page URL. On a returning visit the built-in columns are empty while your custom fields are populated. Report on the custom fields.

Gotchas

Donate Button (Overlay Mode)

Display the form as a modal overlay triggered by a button:

"donate-button": {
  "location": "bottom-right",
  "text": "Donate Now"
}

The donate button floats on the page and opens the form in a modal when clicked. Available positions: bottom-right, bottom-left.

Iframe Mode

When the form is embedded cross-domain or needs additional security isolation, it runs inside an iframe automatically. You can control iframe dimensions:

The form automatically communicates resize events to the parent page so the iframe height adjusts to fit the content.

Additional Options