Embeddable Form — Donately Docs

Quick Start

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.

This documentation covers version 6.x (current production). Version 7.x is a major rebuild and is coming soon.

Simplest Embed

Add a single script tag and a target div to your page:

<script
  src="https://cdn.donately.com/6.0/donately.min.js"
  data-donately-id="act_ba7d12ab27bb"
  data-stripe-publishable-key="pk_live_xxxx"
  defer async>
</script>
<div id="donation-form"></div>

That's it. The form will render automatically with default settings.

Embedding Methods

Method 1: Script Tag Attributes

Pass options directly as data- attributes on the script tag. Best for simple embeds.

<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-amount="50"
  data-presets="25,50,100,250"
  data-currency="usd"
  data-comment="true"
  defer async>
</script>
<div id="donation-form"></div>

Method 2: JavaScript Initialization

Use Donately.init() for full control over options and callbacks.

<script src="https://cdn.donately.com/6.0/donately.min.js" defer async></script>
<div id="my-form"></div>

<script>
  Donately.init({
    selector: '#my-form',
    options: {
      "donately-id": "act_ba7d12ab27bb",
      "stripe-publishable-key": "pk_live_xxxx",
      "donately-form-id": "frm_xxxx",
      "amount": 50,
      "presets": "25,50,100,250",
      "currency": "usd",
      "comment": true,
      "address": true,
      "recurring-options": {
        "frequencies": ["false", "1.month", "12.month"],
        "type": "toggle"
      }
    },
    afterFormLoad: function() {
      console.log('Form loaded');
    },
    onSuccess: function(donation) {
      console.log('Donation complete:', donation);
    },
    onError: function(error) {
      console.error('Error:', error);
    }
  });
</script>

Required Options

Option	Description
donately-id	Your Donately account ID (e.g., `act_ba7d12ab27bb`)
stripe-publishable-key	Your Stripe publishable key (starts with `pk_live_` or `pk_test_`)

Donation Options

Option	Type	Description
donately-form-id	string	Form ID to fetch pre-configured options from the API (e.g., `frm_xxxx`)
amount	number	Default donation amount in dollars
presets	string	Comma-separated preset amounts (e.g., `"25,50,100,250"`)
campaign-id	string	Campaign to attribute donation to
fundraiser-id	string	Fundraiser to attribute donation to
currency	string	ISO currency code (default: `usd`)
donor-pays-fees	boolean	Show option for donor to cover transaction fees
dont-send-receipt-email	boolean	Suppress the automatic donation receipt email

Donor Fields

Control which donor information fields are shown on the form.

Option	Type	Description
email	string	Pre-fill the donor's email address
name	string	Pre-fill the donor's name
address	boolean	Show full address fields (street, city, state, zip, country)
billing-zip	boolean	Show billing zip code field only (lighter than full address)
phone	boolean	Show phone number field
comment	boolean	Show comment/message field
onbehalfof	boolean	Show "on behalf of" / tribute field
anonymous	boolean	Show "make my donation anonymous" checkbox

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"
}

Property	Description
frequencies	Array of frequency options to display. `"false"` = one-time option.
type	Display style: `"toggle"` or default radio buttons

Available Frequencies

Value	Description
false	One-time donation
1.day	Daily
7.day	Weekly
14.day	Bi-weekly
1.month	Monthly
2.month	Bi-monthly
3.month	Quarterly
6.month	Semi-annually
12.month	Annually

Legacy Options

Option	Description
recurring-frequency	Legacy: comma-separated frequencies or JSON array
recurring-start	Start date for the recurring schedule
recurring-stop	End date for the recurring schedule

Payment Methods

Control which payment methods are available on the form.

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

Value	Description
cc	Credit card (legacy Stripe token flow)
card	Credit/debit card via Stripe Elements
wallet	Apple Pay / Google Pay via Stripe
ach	ACH bank transfer via Stripe + Plaid
paypal	PayPal (requires PayPal merchant ID)

Option	Description
payment-options	Comma-separated list of enabled payment methods
payment-options-layout	Layout style: `horizontal` or `vertical`
paypal-merchant-id	PayPal merchant ID (required for 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

Type	Description
text	Single-line text input
email	Email input with validation
textarea	Multi-line text area
select	Dropdown select. Provide `options` array.
radio	Radio button group. Provide `options` array.
checkbox	Single checkbox
select_state	US state dropdown (pre-populated)
select_country	Country dropdown (pre-populated)
select_campaign	Dropdown of account campaigns
select_fundraiser	Dropdown of campaign fundraisers
hidden	Hidden field with preset `value`
section	Visual section divider / heading
cart_items	Merchandise / cart item selector

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

Variable	Description
-PrimaryColor	Main brand / button color
-PrimaryFontFamily	Font family for all form text
-PrimaryFontSize	Base font size
-FormBackgroundColor	Form container background
-FormOuterPadding	Padding around the form
-FieldBackgroundColor	Input field background
-FieldFontColor	Input field text color
-FieldBorderColor	Input field border color
-FieldBorderWidth	Input field border width
-LabelFontColor	Label text color
-ErrorTextColor	Error/validation message color

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.

Option	Description
i18n-locale	Language/locale code
show-language-select	Show a language selector dropdown on the form
custom-translations-url	URL to a custom translation JSON file

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)

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

Section	Description
presets	Preset amount buttons
amount	Custom amount input
donorpaysfees	Donor covers fees checkbox
recurringgroup	Recurring frequency selector
paymentmethods	Payment method selection (card, ACH, PayPal, etc.)
authname	Card holder name
namegroup	First and last name fields
email	Email field
phone	Phone number field
addressgroup	Street address fields
citygroup	City, state, zip fields
countrygroup	Country selector
billingzip	Billing zip code only
comment	Comment / message field
onbehalf	On behalf of / tribute field
anonymous	Anonymous donation checkbox
ecard	E-card configuration
dtd	Double the Donation employer match
summary	Donation summary/review
submit	Submit / donate button

Callbacks & Events

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

Callback	Description
afterFormLoad	Fires when the form has fully rendered and is ready
onSuccess	Fires after a successful donation. Receives the donation object.
onError	Fires on a donation error. Receives the error object.
afterNavigateHook	Fires after step navigation. Receives the current step number.

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);
  }
});

Iframe Events

When the form runs inside an iframe, it communicates with the parent page via postMessage events:

donately.loaded — Form has loaded
donately.success — Donation succeeded
donately.error — Donation failed
donately.resized — Form height changed (for auto-resizing iframes)

Analytics Integration

The form supports built-in tracking for Google Analytics, Google Tag Manager, and Facebook Pixel.

Option	Description
google-analytics-id	Google Analytics property ID (e.g., `UA-XXXXX-X` or `G-XXXXX`)
google-tag-manager-id	Google Tag Manager container ID (e.g., `GTM-XXXXX`)
facebook-pixel	Facebook Pixel ID for conversion tracking
double-the-donation-public-key	Double the Donation public key for employer matching

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:

Option	Description
iframe-height	Custom iframe height in pixels (default: auto-resize)
iframe-width	Custom iframe width (default: `100%`)

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

Additional Options

Option	Type	Description
ecard	JSON	E-card configuration for tribute/memorial donations
tracking-codes	JSON	Custom tracking codes stored with the donation
privacy-policy	string	URL to your privacy policy (displayed as a link on the form)
google-recaptcha-site-key	string	Google reCAPTCHA site key for bot protection
fetch-config	boolean	Fetch form configuration from the API using the form ID (default: `true` when form-id is set)

Embeddable Donation Form