Implementing Web Widgets on your website


This guide is designed for web developers and web designers for the implementation of Web Widgets on to your website.




Web Widgets are a Professional-only feature. Essential subscribers, please contact us to find out more about upgrading.


How Donorfy Web 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

So before you can even get started creating the web pages, the client needs to set up an account with each of:
That's the easy bit! Now you need to build the website pages. To do that you'll need to understand how the integration works:
The Donorfy Web Widget is an API that, when provided with information collected from the web page, will: 
(a) collect the donation via Stripe or
(b) set up a regular gift by Direct Debit with GoCardless, and
(c) populate Donorfy with:
  • 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.

It needs a combination of web design and coding skills (HTML, CSS, maybe some PHP) to arrive at a finished solution.


If the requirement is to collect payments by both Stripe and GoCardless, you will need at least two Web Widgets because each Widget has a number of characteristics:
  • 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

If you would like to collect payments for various appeals, campaigns or currencies, then separate Web Widgets will be required for each combination.


User interface

The Web Widget code generated by Donorfy supplies a basic UI - it is provided only to illustrate the basic information that your web page needs to collect and send it to the Donorfy API.
The design of the online user journey - from clicking a Donate button, and then funnelling them through the various 'products' the client wishes to offer (one-off donations - potentially at suggested amounts, regular gifts, sponsor a (something)....) is entirely up to you and the client to design and assemble using standard features of the CMS in conjunction with your own Javascript, HTML, and CSS coding skills.
The final step is to pass that information to the API using the code provided so that it collects the money and updates Donorfy, as described above.
Important - you should set up your giving pages so you only have one Widget on a page - if you have two Widgets on the same page - even if one is hidden - the Widgets will not work properly.

The important thing is to use the correct field ids, names, lengths, and hidden fields. And to call the API correctly. See below for this information.


What happens when the donation is submitted?

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:

  1. 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)
  2. the donor information on the form and the token are sent to Donorfy
  3. Donorfy collects the payment from Stripe using the token provided earlier
  4. 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.
  5. 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 Financial > Online Donations.


This article guides you through adding a Stripe Web Widget: Creating a Stripe Payment Card Donations Web Widget


Payments via GoCardless

When a donor makes a payment via GoCardless and clicks on the Submit button, the following happens within a few seconds:

  1. The donor is passed through to a GoCardless form where they check their details and complete the remainder of the form, such as sort code, bank account number, confirm any additional signatories that may be required and conforms the T's and C's. These details are then sent directly into GoCardless, and GoCardless returns the donor to the website. A confirmation of the Direct Debit Mandate being created is sent back to Donorfy (Mandate ID)- therefore Donorfy never stores the bank details.
  2. the donor information on the form and the Mandate ID is sent to Donorfy and either added to a new Constituent Profile or matched to an existing one 
  3. a Recurring Payment Instruction is added to the constituent's Timeline, and the recurring payments will be subsequently collected by Donorfy. 
  4. Donorfy collects the first payment from GoCardless using the Mandate ID provided earlier, the payment will be debited circa 7 days later
  5. the donation is added to the constituent's Timeline as a Transaction
  6. subsequent payments will be managed by Donorfy

The process is logged and visible in Financial > Online Donations


This article guides you through adding a GoCardless Web Widget: Creating a GoCardless Web Widget


Website Compatibility

Any modern website system should be able to accommodate a Donorfy Web Widget - WordPress, Wix, Squarespace, etc. 


Your page should use https:// not http://

Your website needs an SSL certificate - i.e. its address should start https - e.g 



We use 2.1.4 for our Web Widgets however, earlier editions of jQuery can be used without any issues, the minimum version of JQuery would be 1.1.11 onwards which should work.

NOTE: whilst WordPress.Org sites (the majority) do support this, their does not.


Testing the Widget


The Stripe widget can only use the Live Publishable Key - do not attempt to use the Test Publishable Key from 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.



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 Financial > Online Donations.

This article has information about troubleshooting common web widget problems


Can I use GoCardless' Sandbox?

No. Donorfy only works with live the GoCardless system.

When testing, as noted in the above Testing the Widget section you will need to create live Direct Debits and then cancel any mandates created whilst testing in the GoCardless dashboard.


Can I connect my GoCardless account to a test Donorfy account?

No. You should not connect one GoCardless account to two Donorfys (your live Donorfy and a test Donorfy account) as this will cause issues with the live submissions and updates from GoCardless to Donorfy. If you want to test using a live GoCardless account then we advise creating a 2nd GoCardless account solely for the purpose of using with your test Donorfy account. 


Generating the HTML code to embed in your website

Follow these instructions to create a Stripe (cards) widget, or these instructions for a GoCardless (Direct Debit) widget.

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:


Are you using Squarespace?

There are some specific steps to getting a widget working in Squarespace, see this article



Don't use iFrames with GoCardless - GoCardless Web Widgets cannot be contained in an iFrame



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 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.



Making the Card Number and associated fields look like the other fields on your page

When the card number, expiry date, and CVC fields are added to your page by Stripe they will not have any styling - e.g. background colour, font size etc - associated with them. You may want to add some styling so these fields are consistent with the rest of your page.

You can use the InitialiseForm function to style the controls that Stripe Elements adds to your page - see the example below - also see the Stripe knowledgebase articles for more info.


function InitialiseForm() {
var elementStyles = {
base: {
color: '#32325D',
fontWeight: 500,
fontFamily: 'Source Code Pro, Consolas, Menlo, monospace',
fontSize: '16px',
fontSmoothing: 'antialiased',
'::placeholder': {
color: '#CFD7DF',
':-webkit-autofill': {
color: '#e39f48',
invalid: {
color: '#E25950','::placeholder': {color: '#FFCCA5',},
var elementClasses = {
focus: 'focused',
empty: 'empty',
invalid: 'invalid',
cardNumber.update({style: elementStyles, classes: elementClasses} );
cardExpiry.update({style: elementStyles, classes: elementClasses} );
cardCvc.update({style: elementStyles, classes: elementClasses} );


Adding additional fields on the widget

You can prompt for additional information on Web Widgets to enrich data collection. See these articles:



This article has information about troubleshooting common web widget problems


Please sign in to leave a comment.
Powered by Zendesk