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 allows script embeds (Webflow, Squarespace, Wix, Drupal, etc.).

<script
  src="https://cdn.donately.com/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/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/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>

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.

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