Skip to main content

Fundraise Up Connections and Settings

The subscription settings for the iPaaS.com Fundraise Up integration — how to obtain each value and how it affects runtime behavior.

The Fundraise Up integration brings Fundraise Up data into iPaaS.com: each donation becomes a Transaction with its Payment and its lines (a designation line, plus a surcharge line for a processing fee the donor covered), and each supporter becomes a Customer with an address. Data flows in one direction, TO iPaaS.com; the integration only reads from Fundraise Up. This article describes how the integration connects to Fundraise Up and every subscription setting it uses. For step-by-step setup, see the Fundraise Up Installation Instructions.

How to Connect

Prerequisites

Before setting up the Fundraise Up integration in iPaaS.com, make sure you have the following:

  • API Key: a Fundraise Up API key created under Settings > API keys in the Fundraise Up dashboard by a user with the Organization Administrator role. The key needs Read on Donations, Supporters, Recurring plans and Events, in the mode the subscription reads (Live data or Test data). Fundraise Up shows the key only once, when it is created.

  • API Url: https://api.fundraiseup.com/v1. Fundraise Up uses the same address for live and test data.

  • Livemode: decide whether the subscription reads live data (True, for production) or test data (False, for staging or UAT), to match the mode your API key was made in.

  • In iPaaS.com: a Payment Method named Other, and a donation product and a surcharge product whose SKUs you enter in the Designation and Surcharge collections before the first transfer (see the Installation Instructions).

Configure Subscription Settings

Open the Fundraise Up subscription in iPaaS.com and provide the following information. Name, Versions and Create Default Mappings are on every subscription; the next five are this integration's settings; the last six are the standard throttle and concurrency fields.

Field

Description

Required

Default or Example

Name

A unique name for the subscription within the company.

Yes

Example: Fundraise Up - Production

Versions

The Fundraise Up integration version.

No

The version chosen in the dropdown

Create Default Mappings

Creates the standard mapping collections and translations.

No

Checked

API Url

The Fundraise Up API address, the same for live and test data. iPaaS.com does not save the subscription with an empty API Url.

Yes

None (the field starts empty); enter https://api.fundraiseup.com/v1

API Key

The Fundraise Up API key. Shown in plain text on the subscription page.

Yes

None

Livemode

True reads live data; False reads test data. A Livemode that doesn't match the key's mode stops each donation with FUUP-VALD-1006.

Yes

None (--select--); select True or False to match the mode your API key was made in

Donation Poll Days

How many days back the first donation poll reads. Not read after the first poll.

No

None (blank reads every donation)

Surcharge As Line Item

Yes puts a processing fee the donor covered on its own line; No keeps one line at the gross amount.

No

None (blank counts as off)

API Throttle Limit

Maximum number of API calls per throttle window.

Yes

500

API Throttle Seconds

Length of each throttle window, in seconds.

Yes

60

API Throttle Limit (to iPaaS.com)

Maximum number of inbound API calls per throttle window.

Yes

500

API Throttle Seconds (to iPaaS.com)

Length of each inbound throttle window, in seconds.

Yes

60

Concurrent Connections

Simultaneous connections for this subscription. Keep at 1 or 2 (see Throttling).

Yes

2

Concurrent Batch Executions

Simultaneous batch operations. This integration does not run batch operations, so the value has no effect on it.

No

10

API Url

The base address for every Fundraise Up API call. Fundraise Up uses the same address for live and test data; the API key and the Livemode setting decide which data is read, not the address. Enter https://api.fundraiseup.com/v1; the field starts empty on a new subscription. A wrong API Url makes transfers fail with FUUP-AUTH-1002 (the address answers and refuses the request) or FUUP-EXTN-1002 (nothing answers at the address). The setting is required: iPaaS.com refuses to save the subscription with an empty API Url.

API Key

The key you created in Fundraise Up's Settings > API keys screen. It needs Read on Donations, Supporters, Recurring plans and Events, in the mode Livemode selects (live or test).

  • Without Events, refunds and recurring plan changes don't arrive by the poll, and FUUP-AUTH-1003 appears under Dashboard / Integration Monitoring / Error Logs; new donations still transfer.

  • Without Recurring plans, an installment's plan fields stay as the donation reported them.

See the Installation Instructions for the step-by-step procedure.

Security notes:

  • Fundraise Up shows the full key only once, when it is created. Copy it to a password manager before closing the Fundraise Up dialog.

  • The key does not expire. To rotate it, create a new key, enter it in this setting, save the subscription, then remove the old key in Fundraise Up.

  • One Fundraise Up API key can carry permissions on Live data, Test data or both. A separate key per iPaaS.com subscription, limited to that subscription's mode, makes rotation and removal simpler.

  • The setting is a plain text field: the key shows on the subscription page, so treat that page as sensitive and don't share screenshots of it.

  • When an error quotes Fundraise Up's answer, it shows only Fundraise Up's message and code, and masks anything that looks like a key.

Livemode

Selects which Fundraise Up data the subscription reads. Select True for live data or False for test data, to match the mode your API key was made in, and check the value before saving. One API key can hold permissions on both; the key must have Read permission in the mode you choose.

If Livemode doesn't match the mode your API key was made in, donations don't transfer. Each such donation stops with FUUP-VALD-1006, which names the Livemode value to set. Make sure Livemode matches the key's mode (Live data or Test data) before the first transfer. A key that reads both Live and Test data also reaches donations made in the other mode, such as test donations on a live subscription, and each of those stops with FUUP-VALD-1006 to dismiss. To avoid that, give a production subscription a key with Read on Live data only.

Livemode

The API key needs Read on

Use for

True

Live data

Production subscription

False

Test data

Staging or UAT subscription

Livemode is a required True/False setting. iPaaS.com saves only these two values for it, in any letter case (it stores them in its own case), and refuses any other value, such as a typo like Flase, when you save the subscription. A staging subscription must be set to False.

Changing Livemode on a subscription that has already transferred donations would mix records from two separate sets of Fundraise Up data under one subscription: see Livemode is set once for the life of a subscription in Fundraise Up Known Limitations. Use a separate subscription for each mode.

Donation Poll Days

Bounds how far back the first donation poll on a new subscription looks. When the first scheduled donation poll runs, the integration asks Fundraise Up only for donations created in the last N days, and reads them all. After that first run, every later poll continues from the last donation it read, and Donation Poll Days no longer applies. There is no Initialize Data step: this first poll is the only way to bring in donations made before the subscription.

Choose the value before the first scheduled poll runs:

  • 7: only the last week of donations is imported. Suitable when you only need donations from the install date forward.

  • A larger value (for example 365, 730 or 1825): imports one, two or five years of donations on the first run. Lowering it later does not remove records already imported.

  • 0 (or blank on a new subscription): no limit; the first run reads every donation in the Fundraise Up account. The field starts empty on a new subscription, so enter a value before the first poll unless you want every donation.

  • Anything else (a negative number such as -5, or text such as abc or 7 days) stops the first poll with FUUP-VALD-1004, so a typo never imports your whole history. Correct it and save; the next scheduled poll then runs as the first poll.

The setting is read only while the subscription has no saved poll position. After the first poll has completed, changing it has no effect, and a later invalid value raises no error.

A donation whose transfer fails is not read again by a later poll unless it changes in Fundraise Up. Re-send it from Dashboard / Integration Monitoring / Error Logs or with a Manual Sync once the cause is fixed. See The poll runs on a schedule you create, and continues from the last donation it read in Fundraise Up Known Limitations.

Surcharge As Line Item

Splits a processing fee the donor chose to cover into its own Transaction Line. Fundraise Up lets donors add the processing fee to their gift. With this setting on, such a donation reaches iPaaS.com with two lines: the designation line for the gift before the fee, and a surcharge line for the fee. The Transaction Total and the Transaction Payment stay at the amount charged, so the lines add up to the Total and the Payment. For example, a $5.00 gift with a $0.70 covered fee becomes a $5.00 designation line, a $0.70 surcharge line, a $5.70 Total and a $5.70 Payment.

  • Yes, True, 1 and On turn it on: the designation line plus a surcharge line for the fee. No, False, 0 and Off leave it off: the donation is one designation line at the gross amount charged. Any other value (a typo such as Yse) stops each donation transfer with FUUP-VALD-1002, which names the value. Correct the setting, save, then re-send the donations that failed from the error log or with a Manual Sync: a later poll does not read them again.

  • On a new subscription the field starts empty, which counts as off.

  • iPaaS.com does not save a blank value for this setting once it has one: clearing it and saving keeps the previous value.

  • A subscription saved before the setting existed has no value, which counts as off. Before turning it on there, follow the steps in the Fundraise Up Version 1.0.3 Upgrade Guide. See also A processing fee the donor covers can arrive as its own line in Fundraise Up Known Limitations.

  • The surcharge line is mapped by the Add/Update Fundraise Up Surcharge TO iPaaS.com collection. Its Sku must name an existing iPaaS.com Product.

  • The fee itself is always available on the Transaction custom field Donor Covered Fee, whichever way this is set, when the Donor Covered Fee mapping is present (it is included in the default mappings; a subscription created before this update adds it by following the Fundraise Up Version 1.0.3 Upgrade Guide).

  • Turning it on for an existing subscription changes only donations transferred from then on. Donations already imported keep their single line until they are transferred again.

  • Turning it off later: a donation already transferred with a surcharge line keeps that split when it is transferred again, so its lines still add up to the Total. Donations first transferred after the change arrive as one line.

Authentication Methods

Method: API Key (bearer token)

The integration authenticates with the Fundraise Up API key alone. It sends the key with every request as a bearer token, together with the subscription's Livemode value, which tells Fundraise Up whether to read live or test data. There is no OAuth sign-in, no token refresh and no per-request signature, and nothing is stored when the integration connects: the only secret is the API key in the subscription settings.

At the start of every transfer, the integration checks the connection by reading one donation from Fundraise Up. If Fundraise Up refuses the key, the transfer stops and Dashboard / Integration Monitoring / Error Logs shows FUUP-AUTH-1002 with Fundraise Up's reason. If Fundraise Up is busy or doesn't answer the check, the transfer goes on and its own request reports the condition. Unable to connect to subscription with no other detail means the API Key is empty or Livemode holds a value other than True or False. Correct the setting, save the subscription, and re-send the donation.

A Livemode that doesn't match the mode the API key was made in passes the check, and each donation then stops with FUUP-VALD-1006 (see Livemode).

Fundraise Up Webhook

The integration fully supports webhooks once the webhook is configured. The webhook is configured manually by the subscriber in Fundraise Up (Settings > Webhooks): Fundraise Up offers no way to create a webhook from outside its dashboard, so it is not a subscription setting. The Installation Instructions give the address to paste (built from the subscription's Webhook API Key) and the events to tick. Nothing needs to be turned on in iPaaS.com: the integration's webhook scopes need no activation.

What each Fundraise Up event does:

  • Donation created: accepted and ignored. A new donation's Transaction is created by the Donation successful event.

  • Every other donation event (for example Donation successful, Donation updated or Donation refunded): reads the donation again and adds or updates its Transaction. A refund sets the Transaction and its Payment to Refunded.

  • Every recurring plan event (for example activated, canceled or payment terms updated): sends the plan's latest donation again, with the plan's current status and details.

  • Tribute, Supporter and any other events: accepted, and nothing is transferred.

iPaaS.com refuses a delivery whose address has a wrong or missing Webhook API Key, and nothing is transferred. A webhook delivery reaches iPaaS.com within seconds, so new donations, refunds and recurring plan changes arrive almost at once. The scheduled donation poll stays as the backstop: it brings anything the webhook missed, or everything when no webhook is configured, and it skips a new donation a webhook already delivered.

Scopes

The integration's scopes appear in iPaaS.com event and activity views. None needs to be turned on, and only transaction/poll is used when you set something up (the scheduled poll event).

Scope

What it does

transaction/poll

The scheduled donation poll. Choose it on the Webhook Poll Request event you schedule under Dashboard / Integration Monitoring / Events.

donation.updated

A Fundraise Up donation webhook (any donation event except Donation created): the donation is read again and its Transaction added or updated.

recurring_plan.updated

A Fundraise Up recurring plan webhook (any recurring plan event): the plan's latest donation is sent again.

transaction/created

A donation transfer that creates a Transaction.

transaction/updated

A donation transfer that updates a Transaction.

customer/created

A supporter transfer that creates a Customer.

customer/updated

A supporter transfer that updates a Customer.

Initialization Support

Initialization (a bulk import from the subscription page) is not supported for Fundraise Up in iPaaS.com: no collection offers Initialize Data. Donations made before the subscription arrive only through the first scheduled poll, which reads the window set by Donation Poll Days (see above). Set that value before the first poll runs.

Throttling

Throttling keeps the Fundraise Up API from being overwhelmed. The throttle and concurrency fields are standard iPaaS.com subscription settings, filled in by the subscription form; the integration does not set them, so check them after you subscribe. For more details, refer to Subscription Configuration - Edit.

Fundraise Up limits the number of requests in progress at once, not the number per minute:

  • Each Fundraise Up account can have 3 API requests in parallel, across all endpoints and all API keys of the account, test or live.

  • Additional requests are refused with HTTP 429 Too Many Requests and the code concurrent_requests_limit_exceeded. Fundraise Up advises keeping an integration single-threaded.

  • A parent account and its subaccounts are counted separately.

How this maps to the iPaaS.com subscription:

  • Concurrent Connections is the setting for this limit. Set it to 1 (single-threaded, as Fundraise Up advises) or 2 (still below the limit of 3, with one request of headroom). Do not exceed 2. With a higher value, Fundraise Up refuses some requests as too many at once, and those transfers are retried after about 60 seconds with FUUP-EXTN-1005.

  • API Throttle Limit and API Throttle Seconds (and their to iPaaS.com counterparts) limit the number of calls per time window; they cannot prevent parallel requests. Leave them at their defaults (500 calls per 60 seconds).

  • The limit of 3 is shared by every API key of the account. If two iPaaS.com subscriptions read the same Fundraise Up account (for example a staging subscription on test data and a production subscription on live data), the sum of their Concurrent Connections values must stay at or below 3.

  • When Fundraise Up does refuse a request with HTTP 429, the integration tells iPaaS.com to wait about 60 seconds before it tries again. The message carries the code FUUP-EXTN-1005. If it repeats, set Concurrent Connections to 1 or 2.

For Fundraise Up's own description, see Fundraise Up: Rate limits in the Fundraise Up API documentation.

Related Documents

Did this answer your question?