Hash functions

Learn what function hashes serve in our Upgrade Links, and how you can create links that use hash functions.

Understanding hash functions

Hash functions allow you to securely reduce donor friction by eliminating the need for additional confirmation when a supporter opts to increase their donation using your Upgrade Links.

A hash function is a mathematical function that transforms a given set of data (in this case the secret key, Supporter ID and Recurring ID) into one bit string of fixed size. Once a hash value has been generated, it is impossible to convert it back into the original data, making the hash fully secure. The type of hash function used for our Upgrade Links is SHA256.

If using links without a hash function, supporters will also be required to confirm their donation increase in an email, sent to them automatically by Fundraise Up. If using links with a hash function, this extra step is not required. This is because the use of the hash, created using the organization’s secret key from Fundraise Up, already pre-confirms definitively that the link was created by the organization and is legitimate.

Because the use of a hash removes the final confirmation email step for supporters, upgrade conversion is likely to be noticeably better if hash functions are used.

Hash functions must be very carefully distributed to ensure no errors are made. If links with a hash function are sent to the wrong supporters, they will be able to increase donation amounts for other supporters. If you made a mistake, contact the Fundraise Up Support team immediately so that we can reset the secret key and, in doing so, disable all your links that use the hash function.

Step 1: Gather the information you need

You need the following information to create Upgrade Links with a hash function:

  • Your organization’s Basic Link and Secret Key. Find both of these in the Dashboard by going to Settings Recurring plans Upgrade Links.
  • The Recurring ID of the recurring plan you’re planning to offer an increase on, as well as the supporter’s Supporter ID. These can be easily exported from the Dashboard.
How to export your recurring supporters’ Recurring ID and Supporter ID.

Step 2: Create and test the hash for your links

To create a signature (hash), you need to apply the SHA256 algorithm. For the input data, you need the following parameters:

  • RecurringID
  • SupporterID
  • SecretKey
1Signature = getSignature(RecurringID + SupporterID + SecretKey)

Example in pseudocode

1const crypto = require('crypto')
2
3function getSignature(RecurringID, SupporterID, SecretKey) {
4  return crypto.createHash('sha256')
5               .update(`${RecurringID}${SupporterID}${SecretKey}`)
6               .digest('hex')
7}
8
9function verifySignature(RecurringID, SupporterID, SecretKey, Signature) {
10  return getSignature(RecurringID, SupporterID, SecretKey) === Signature
11}

An example of the creation and verification of a hash using JavaScript

1import hashlib
2    
3def getSignature(RecurringID, SupporterID, SecretKey):
4  return hashlib.sha256(f"{RecurringID}{SupporterID}{SecretKey}".encode()).hexdigest()
5
6def verifySignature(RecurringID, SupporterID, SecretKey, Signature):
7  return getSignature(RecurringID, SupporterID, SecretKey) == Signature

An example of the creation and verification of a hash using Python

Step 3: Assemble the links

Choose which type of link you want to create, and use the following structures:

Main donation upgrade

1[BasicLink]
2  ?recurring=[RecurringID]
3  &supporter=[SupporterID]
4  &signature=[Signature]

How to construct a main donation Upgrade Link with a hash function

1https://mycharity.donorsupport.co/upgrade?recurring=RXXXXXXX&supporter=HSXXXXXXX&signature=27c05162f113015eee93fb024089bf75933314273fb27724409055f72233dc51

An example of a main donation Upgrade Link with a hash function

Cost coverage upgrade

1[BasicLink]
2  ?mode=covering_costs
3  &recurring=[RecurringID]
4  &supporter=[SupporterID]
5  &signature=[Signature]

How to construct a cost coverage Upgrade Link with a hash function

1https://mycharity.donorsupport.co/upgrade?mode=covering_costs&recurring=RXXXXXXX&supporter=SXXXXXXX&signature=27c05162f113015eee93fb024089bf75933314273fb27724409055f72233dc51

An example of a cost coverage Upgrade Link with a hash function.

Step 4: Distribute the links

Fundraise Up does not distribute these links in emails to supporters. We recommend using a CRM service, such as Mailchimp, to distribute individual links to your recurring supporters. This can also be done via SMS and other direct communication channels.

 

In this article