Hash Functions

Learn what function hashes serve in our Upgrade Links, and how you can create links that use 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 givetly. 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 givetly, 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.

⚠️ Caution: 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 Support team immediately so that we can reset the secret key and, in doing so, disable all your links that use the hash function.

​

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

Signature = getSignature(RecurringID + SupporterID + SecretKey);

Example in pseudocode:

const crypto = require("crypto");



function getSignature(RecurringID, SupporterID, SecretKey) {

  return crypto

    .createHash("sha256")

    .update(`${RecurringID}${SupporterID}${SecretKey}`)

    .digest("hex");

}



function verifySignature(RecurringID, SupporterID, SecretKey, Signature) {

  return getSignature(RecurringID, SupporterID, SecretKey) === Signature;

}

Example in Python:

import hashlib



def getSignature(RecurringID, SupporterID, SecretKey):

  return hashlib.sha256(f"{RecurringID}{SupporterID}{SecretKey}".encode()).hexdigest()



def verifySignature(RecurringID, SupporterID, SecretKey, Signature):

  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:

[BasicLink]?recurring=[RecurringID]&supporter=[SupporterID]&signature=[Signature]

Example:

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

Cost coverage upgrade:

[BasicLink]?mode=covering_costs&recurring=[RecurringID]&supporter=[SupporterID]&signature=[Signature]

Example:

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

​

Step 4: Distribute the Links

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.