Summary
Version 1.0.3 of the Fundraise Up integration adds new default mappings, a new Transaction Line collection, new Payment Method translation rows and a new subscription setting. These ship as changes to the integration's default template.
A subscription keeps the mapping collections it was created with: template changes are not applied to existing subscriptions. This guide is for subscriptions created before this update. A subscription created from the current template already has everything below and needs none of these steps.
Nothing is required. A subscription created before this update keeps transferring supporters and donations with its existing collections, and the new Surcharge As Line Item setting reads as off when it has no value. Make only the changes for the features you want. iPaaS.com recommends that subscribers or their MiSP make the changes on a test subscription first, if they have one, confirm that donations transfer as expected, and then repeat the changes on production.
The sections below are grouped by what you add. A summary checklist is provided at the end.
Before You Begin
Create each custom field before you add the mapping that writes to it. In the mapping editor, click + Add Custom Field in the destination picker to create a Transaction or Transaction Line custom field inline.
Use the formulas from the current template. The formula for every mapping in this guide is in the Fundraise Up to iPaaS.com Donation Mapping Documentation and the Fundraise Up to iPaaS.com Supporter Mapping Documentation. Copy each one exactly.
Downstream systems read these fields by name. A system that receives donations through iPaaS.com (for example Raiser's Edge NXT) reads the new custom fields and Line Type by name, and gets empty values until they are added. Use the names exactly as shown.
Donation Details: Add/Update Fundraise Up Donation TO iPaaS.com
The current template writes recurring plan, consent, benefit, tribute, refund, donor comment and covered-fee details to Transaction custom fields. Each value is empty when the donation has no such detail. Add the groups you want; each group is independent.
Recurring plan details
Add the Transaction custom fields and their mappings: Recurring Plan Id, Recurring Plan Status, Recurring Plan Frequency, Recurring Installment, Recurring Plan Start Date, Recurring Plan Ended Date and Recurring Next Installment Date.
Each recurring installment then carries its plan's current status, frequency, installment number and dates.
Consent details
Add the Transaction custom fields and their mappings: Consent Email, Consent Phone, Consent Mail, Consent SMS and Consent Social.
Benefit details
Add the Transaction custom fields and their mappings: Benefit State, Benefit Fair Market Value, Benefit Fair Market Value Currency, Benefit Name, Benefit Option and Benefit Ship To.
Tribute details
Add the Transaction custom fields and their mappings: Tribute Type, Tribute Honoree, Tribute From, Tribute Message, Tribute Notify Address, Tribute Notify Name and Tribute Notify Email.
Refund, comment and covered-fee details
Add the Transaction custom fields and their mappings: Refunded At, Donor Comment and Donor Covered Fee. Refunded At receives the refund date when a donation is refunded. Donor Covered Fee carries the processing fee the donor covered, whatever the Surcharge As Line Item setting.
Add the TotalQty mapping with the Static value 1.
Optional: remove the sample mappings
Earlier templates shipped two sample custom-field mappings, TestName1 and Livemode, as examples to delete before going live. If your collection still has them, you can delete them.
Existing Customers: Add/Update Fundraise Up Supporter TO iPaaS.com
A supporter links to an existing iPaaS.com Customer with the same email. The current template keeps that Customer's own values with three Dynamic Formula mappings:
CustomerNumber: if it is a Field mapping (supporter Id), replace it with the current template's formula. A new Customer still gets the Fundraise Up supporter id as its Customer Number; an existing Customer keeps the number it already has.
Company and Comment: add the current template's formulas. Fundraise Up doesn't send a company or a comment, so without these mappings a supporter transfer clears the Company and Comment of a Customer that another system created.
If several integrations in your company write the same Customers, decide which one owns the Customer Number before making this change.
Designation Lines: Add/Update Fundraise Up Designation TO iPaaS.com
Every donation has a designation line, written by this collection. What you add depends on whether your subscription already has the collection.
If your subscription doesn't have this collection:
Create the Transaction Line custom fields the collection writes, including Line Type and grouped_donation_id, plus designation_id, designation_code, designation_name, campaign_id, campaign_code and campaign_name.
Add the collection as a child of the Donation collection, with its filter and all 15 of its mappings from the current template.
Set its Sku mapping to the SKU of an existing iPaaS.com Product.
If your subscription already has this collection:
Create the grouped_donation_id and Line Type Transaction Line custom fields.
Add the grouped_donation_id mapping. When a donor splits one checkout across several designations, Fundraise Up makes a separate donation for each; this field ties their Transactions back to the one checkout.
Add the Line Type mapping with the Static value Donation. If the collection writes the line custom field Raisers Edge NXT LineType, Line Type replaces it; the template no longer writes it.
Add the collection filter, which keeps the designation line and leaves the fee line to the Surcharge collection:
// Keeps the designation line; the donor-covered fee line goes to the Surcharge collection. return !IsSurcharge;
Either way: the Sku must name an existing iPaaS.com Product. Otherwise every donation fails with NFND-1003 - Product Id: … does not exist or can not be found.
Optional: Split a Donor-Covered Fee onto Its Own Line
When Surcharge As Line Item is Yes, a processing fee the donor covered arrives as its own fee line, and the designation line carries the gift before the fee. The Transaction total and Payment stay at the amount charged. Skip this section to keep one line for the full amount charged.
Do these steps in this order, and turn the setting on last:
Create a Product for the fee in iPaaS.com.
Prepare the Designation collection: add its filter (see Designation Lines above). If its UnitPrice and ExtendedPrice mappings are Dynamic Formulas that read the donation amount, replace them with the current template's Field mappings UnitPrice and ExtendedPrice, which carry the gift before the fee when the fee is split. Otherwise the designation line keeps the full amount charged and the lines add up to more than the Transaction total.
Add the Add/Update Fundraise Up Surcharge TO iPaaS.com collection as a child of the Donation collection, with its filter and all 8 of its mappings from the current template. Set Line Type to the Static value Fee and the Sku to the fee Product's SKU. Its filter is shown below.
Set Surcharge As Line Item to Yes in the subscription settings and save.
The Surcharge collection's filter keeps only the fee line:
// Keeps only the donor-covered fee line; the designation line goes to the Designation collection. return IsSurcharge;
Until all four steps are done, leave Surcharge As Line Item at No, or without a value on a subscription that has never saved it. Turned on without the Designation filter, the fee arrives as a second designation line. See A processing fee the donor covers can arrive as its own line in Fundraise Up Known Limitations.
Payment Methods: FundraiseUp Payment Method -> iPaaS Method
The current translation covers all 25 payment methods Fundraise Up publishes. Add rows for the three methods earlier templates didn't have: nz_becs_direct_debit, swish and pix, each to Other, or to one of your own Payment Methods.
Optional: Fundraise Up Webhook
Without a webhook, new donations, refunds and recurring plan changes arrive on the next scheduled poll. To receive them within seconds, create the webhook by hand in the Fundraise Up dashboard under Settings > Webhooks. The scheduled poll stays as the backstop. See Fundraise Up Installation Instructions for the steps.
Check Concurrent Connections
Fundraise Up allows 3 requests at a time per account. Set Concurrent Connections to 1 or 2, and keep the total across all subscriptions on one Fundraise Up account at 3 or less. With a higher value, some transfers are refused as too many at once and retried after about 60 seconds with FUUP-EXTN-1005.
Renamed Source Fields
Some Donation source fields have new names: RecurringPlanAmount, RecurringPlanAmountInDefaultCurrency, RecurringPlanCurrency, RecurringPlanCancellationReason and RecurringPlanCancellationDetails are now LiveRecurringPlanAmount, LiveRecurringPlanAmountInDefaultCurrency, LiveRecurringPlanCurrency, LiveRecurringPlanCancellationReason and LiveRecurringPlanCancellationDetails, and TributeRecipientEmail is now TributeSharingRecipientEmail. Existing mappings and formulas that use the old names keep working. The old names no longer appear in the field picker, so use the new names in new or edited mappings.
Removed Source Fields
These source fields are no longer offered in the field picker. None of them changes how donations transfer in this version:
DesugnationCode and TributeSharingRecepient (Donation) were misspelled copies that stopped carrying a value in version 1.0.2. Use DesignationCode and TributeSharingRecipient instead.
Livemode (Donation and Supporter) and TypeId (Donation, Supporter, Supporter Address and Payment) never carried a Fundraise Up value. You can delete any mapping that uses them.
Sample Upgrade Checklist
Task | Location | Notes |
Add the recurring plan custom fields and mappings | Add/Update Fundraise Up Donation TO iPaaS.com | Recurring Plan Id, Recurring Plan Status, Recurring Plan Frequency, Recurring Installment, Recurring Plan Start Date, Recurring Plan Ended Date, Recurring Next Installment Date |
Add the consent custom fields and mappings | Add/Update Fundraise Up Donation TO iPaaS.com | Consent Email, Consent Phone, Consent Mail, Consent SMS, Consent Social |
Add the benefit custom fields and mappings | Add/Update Fundraise Up Donation TO iPaaS.com | Benefit State, Benefit Fair Market Value, Benefit Fair Market Value Currency, Benefit Name, Benefit Option, Benefit Ship To |
Add the tribute custom fields and mappings | Add/Update Fundraise Up Donation TO iPaaS.com | Tribute Type, Tribute Honoree, Tribute From, Tribute Message, Tribute Notify Address, Tribute Notify Name, Tribute Notify Email |
Add the Refunded At, Donor Comment and Donor Covered Fee custom fields and mappings, and TotalQty (Static 1) | Add/Update Fundraise Up Donation TO iPaaS.com | |
Optional: delete the sample mappings TestName1 and Livemode | Add/Update Fundraise Up Donation TO iPaaS.com | Earlier templates shipped them as examples. |
Replace the CustomerNumber mapping and add the Company and Comment mappings | Add/Update Fundraise Up Supporter TO iPaaS.com | Keeps an existing Customer's number, company and comment. |
If the collection is missing: add it with its filter and all 15 mappings | Add/Update Fundraise Up Designation TO iPaaS.com | Create its Transaction Line custom fields first. |
If the collection exists: add the grouped_donation_id and Line Type (Static Donation) mappings and the filter | Add/Update Fundraise Up Designation TO iPaaS.com | Create the two Transaction Line custom fields first. |
Set the Sku to an existing iPaaS.com Product | Add/Update Fundraise Up Designation TO iPaaS.com | Otherwise every donation fails with NFND-1003. |
Optional: create the fee Product, prepare the Designation collection, add the Surcharge collection, then set Surcharge As Line Item to Yes | Add/Update Fundraise Up Surcharge TO iPaaS.com; then Subscription Settings | Do the steps in this order. |
Add rows for nz_becs_direct_debit, swish and pix | FundraiseUp Payment Method -> iPaaS Method | Each to Other, or to your own Payment Methods. |
Optional: create the Fundraise Up webhook | Fundraise Up dashboard, Settings > Webhooks | The scheduled poll stays as the backstop. |
Set Concurrent Connections to 1 or 2 | Subscription Settings | Keep the total across subscriptions on one Fundraise Up account at 3 or less. |
Optional: switch mappings to the renamed fields | Add/Update Fundraise Up Donation TO iPaaS.com | Old names keep working. |
Optional: replace or delete mappings on removed fields | Donation, Supporter, Supporter Address and Payment collections | DesugnationCode, TributeSharingRecepient, Livemode, TypeId. None of them carries a value. |
Changes That Need No Action
Refunds and recurring plan changes made in Fundraise Up also arrive on the next poll, with no setup.
Error messages carry FUUP codes; see Fundraise Up Error Messages.
Livemode accepts only True or False, and Donation Poll Days must be a whole number of days, 0 or more.
Supporters link to an existing iPaaS.com Customer by email.
A key Fundraise Up refuses now stops the transfer with FUUP-AUTH-1002 and Fundraise Up's reason, instead of only "Unable to connect to subscription".
A donation that isn't in the mode Livemode selects, but is in the other mode, now stops with FUUP-VALD-1006 instead of transferring nothing with no error. If the subscription's key reads both Live and Test data, test donations on a live subscription (or the reverse) now show this error to dismiss; give a production subscription a key with Read on Live data only to avoid them.
A donation that isn't linked yet is matched to the iPaaS.com Transaction whose Transaction Number is its donation id, and that Transaction is updated instead of a duplicate being made. If two or more Transactions (or, for a supporter, two or more Customers with the email) match, the transfer stops with FUUP-BIZL-1001; remove or merge the duplicates and re-send.
