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.

How to create links with a 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.

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)

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}

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

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]

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

Cost coverage upgrade

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

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

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.