Embedding the donation form
Two lines of HTML. Works on any website — WordPress, Wix, Squarespace, or hand-written pages.
The snippet
Paste this where the form should appear. Replace the data-orgvalue with the organisation’s Hopely address, which the administrator can copy from Settings → Website integration.
<div id="hopely-donate"></div>
<script src="https://hopely.co.za/embed.js" data-org="your-organisation-slug"></script>The script creates an iframe, sizes it to the form, and keeps it sized as the form grows. Nothing else on your page is touched: our styles cannot affect your site and yours cannot affect the form.
Options
| Attribute | Does what |
|---|---|
data-org | Required. Which organisation the donation goes to. |
data-campaign | Attributes donations to a campaign. Use the campaign’s address, not its title. |
data-target | The id of the element to mount into, if you would rather not use hopely-donate. |
Any utm_source, utm_medium and utm_campaignon your page’s own URL are carried through to the donation automatically, so a gift can be traced back to the post or advert that produced it.
Allowing your website
The form only renders on addresses the organisation has listed. The administrator adds them under Settings → Website integration.
Addresses match exactly
https://example.org.za allows precisely that. It does not allow https://www.example.org.za, http://example.org.za, a different port, or any subdomain. There are no wildcards.
Most sites serve on one and redirect the other. List the one visitors actually end up on — and if you are unsure, list both. Getting this wrong produces a blank space where the form should be and a security error in the browser console, with nothing in the network tab to explain it.
Reacting to a completed donation
The embed raises an event on your page when a donation is submitted, so you can fire your own analytics or swap in your own thank-you message.
document.getElementById('hopely-donate')
.addEventListener('hopely:donation-success', function (event) {
// event.detail.amount — the donation amount, in rands
console.log('Thank you!', event.detail.amount)
})The amount is the only detail sent. Donor names, email addresses and identity numbers never leave the form.
When it does not appear
| What you see | Almost always |
|---|---|
| Blank space, and a Content Security Policy error in the console | Your address is not on the allowed list, or is listed in a slightly different form — www. against the bare domain is the usual culprit. |
| “This donation form is not available” | The integration is switched off, or data-orgdoes not match any organisation. Check it against Settings → Website integration. |
| Nothing at all, no iframe in the page | No element with the target id. The <div> must exist and its id must match. |
| It worked, then stopped after a settings change | Changes can take up to a minute to take effect. Wait, then reload. |
Want your own form design instead, or a live progress bar? See the JSON API. It is considerably more work and needs a setup step from us before donations can be submitted, so use the embed unless you have a reason not to.