This guide is designed for web developers and web designers.
How Donorfy widgets work
A web widget is HTML code that can be embedded into most modern websites to enable online donations to be collected. Donorfy provides two kinds of web widget:
- for single and recurring donations by payment cards (debit/credit cards), using the Stripe payment gateway
- for recurring donations by Direct Debit, using the GoCardless payment gateway
- Stripe - for donations via credit/debit card - do this in Donorfy, Settings, Stripe Connect
- GoCardless - for Direct Debit donations - do this in Donorfy, Settings, GoCardless Connect
- a new donor (we call them constituents), unless it already exists
- a new donation (a Transaction - if a single donation was made)
- a Recurring Payment Instruction (if a recurring donation was set up)
- a Gift Aid Declaration. So it needs a combination of web design and coding skills (CSS, maybe some PHP) to arrive at a finished solution like the examples given.
- whether it's Stripe or GoCardless
- and the following settings which affect how the donation is categorised when it reaches Donorfy
- the Product
- the Campaign
- the Payment Method
- the Fund
The important thing is to use the correct field ids, names, lengths and the hidden fields. And to call the API correctly. See below for this information.
What happens - Payment Cards via Stripe
When a donor makes a payment card donation and clicks on the Submit button, the following happens within a few seconds:
- The card details are sent directly to Stripe, and Stripe returns to the website a 'token' representing that card (therefore Donorfy never stores the card details)
- the donor information on the form and the token are sent to Donorfy
- Donorfy collects the payment from Stripe using the token provided earlier
- the donor is added (if new) to Donorfy as a new Constituent and the donation is added to the constituent's Timeline as a Transaction.
- If the donor made a recurring donation by card, a Recurring Payment Instruction is added to the constituent's Timeline, and the recurring payments will be subsequently collected by Donorfy.
The process is logged and visible in Actions | Review Web Site Updates.
Any modern website system should be able to accommodate a Donorfy web widget.
Your website needs an SSL certificate - so the page containing the widget needs to be https://yoursite.org/donate (for example).
Your website needs to jquery version 1.9 or later. NOTE: whilst WordPress.Org sites (the majority) do support this, their WordPress.com does not.
The Stripe widget can only use the Live Publishable Key - do not attempt to use the Test Publishable Key from Stripe.
Testing the widget
For Stripe, to do a complete end to end test you need to use a real card and submit small test donations, of say £1. You will see the donation in the constituent's Timeline.
For GoCardless you can create a live Direct Debit using real bank account information, see it in the constituent's Timeline and cancel the DD in GoCardless before it gets to claim it.
In both cases you will see the processing information logged in Actions | Review Web Site Updates.
Generating the HTML code to embed in your website
Copy the generated HTML so that you can embed it into a page on your website.
Adding the widget to your website
Create a new page on your website. Paste the HTML that you copied in the previous step into the new page. Ensure that you are pasting it as HTML code, not as content to be displayed on the page (in WordPress for example, make sure you have the Text tab highlighted:
Modifying and styling the widget
You will want to modify the widget so that it is styled nicely into your website. You may also want to default certain values or hide fields. Within reason you can do what you like here to make the widget appear and behave as you wish.
The key things are that you must NOT change are:
- The form tag
- The ids, names and maximum field lengths of the input fields
- The hidden fields at the end of the generated HTML - after the comment 'Do not change these values' - these are used to control the operation of the widget.
More fields on the widget
You can prompt for additional information on web widgets. See these articles: