How To Use Preconfigured Giving Links

Basic Customer Requirements

To be eligible to take advantage of the Pushpay Preconfigured Giving Links feature, customers need to have access to all of the following:

  1. Pushpay
  2. Pushpay API (recommended)

If a customer does not want to consume Pushpays API, they will not be able to take full advantage of the rich features that the Preconfigured Giving Links can offer.

Authorization and Scope

For authorization, customers are required to use either OAuth2 (Code Flow or Client Flow) as documented here: https://pushpay.io/docs/security

Third party developers are required to use Code Flow.

When requesting authorization, the following scopes should be sufficient:

Scope Description
read Read-only access to resources owned by the subject claim of the token
merchant:view_payments View/search payments for in-scope merchants
lists_my_merchants List merchants that you are an administrator for
merchant:view_recurring_payments View/search recurring gifts and their schedules
merchant:view_community_members View/search for donors

Preconfigured Giving Link Parameters

To launch the Pushpay giving experience, a Preconfigured Giving Link must be constructed. This consists of a handle for the Pushpay Merchant Listing plus a set of optional parameters.

Note! Your merchant handle will look like: pushpay.com/g/merchantlistinghandle

All fields are optional and should be joined by an ampersand (&) character. The parameter string should be preceded by a question mark (?) following the listing handle. For example:

Field String Values Example Notes
Merchant Listing Handle n/a Text /g/merchantlistinghandle The merchant listing handle is used to construct the URL.
Amount a Number a=10 The amount of money a end user may want to donate in the configured currency of the listing (not the donor).
Amount Lock al True, False al=true ‘True’ makes the amount field read-only, so the amount set with the parameter cannot be changed.
Fund fnd Fund name or fund API key fnd=tithes Can specify any fund, not just those set as visible for the listing. The link should use f[0] or fnd, not both. If the fund name choice contains a space the spaces must be replaced with "%20" or the link could error.
Fund Visibility fndv Show, Hide, Lock fndv=lock 'Lock' displays the selected fund as a read-only value. 'Hide' removes the fund selection dropdown box from the page entirely.
Recurring Visibility rcv True, False rcv=false False hides the recurring/one-time selector. If a recurring schedule is specified with the r parameter, the schedule selector will display. If no value is set, rcv defaults to true.
Recurring Start Date rsd Date (yyyy-mm-dd) rsd=2019-10-12 This selects the date of when the first recurring gift will be sent.
Recurring End Type ret Never, Date, Occurrences ret=date Sets whether or not the gift has an end date or fixed number of occurrences.
Recurring End Date red Date (yyyy-mm-dd) red=2019-11-11 If ‘Recurring End Type’ is set to Date, you can specify the date you want to terminate the recurring schedule.
Recurring End Occurrence reo Number reo=4 If ‘Recurring End Type’ is set to Occurrences, you can specify the number of occurrences before the end of the recurring schedule.
Reference f[x] Fund name or reference field choices f[0] = ReferenceFieldName Reference fields use the name of the field and the order in which they occur on the Listing. If the fund name or reference field choice contains any whitespaces, the spaces must be replaced with "%20" or the link will error. Fields start at f[0] and increment by 1, so f[0], f[1], f[2], etc.
First Name ufn Text ufn=FirstName
Last Name uln Text uln=LastName
Email Address ue Text ue=email@domain.com
Mobile Number up Number up=%2B15417543010

Mobile numbers should be inputted without any whitespaces. The default mobile input format is set to US (international).

If the number is a US number, the country code may be appended (optional).

If the number is not a US number, the country code must be appended and prefixed with “%2B” in the url (“+” symbol).

e.g. For a US number where the Country code is +1 and the National number is 541-754-3010, valid url parameter formats include "up=%2B15417543010" and "up=5417543010"

Further reference: https://en.wikipedia.org/wiki/List_of_mobile_telephone_prefixes_by_country
Source Reference sr Alphanumeric sr=fm12345 This can be any reference value, which will be passed back with a redirect URL as a query string parameter alongside a payment token.
Note nt Text nt=This%20is%20a%20note Can be used for storing the information associated with the payment, such as participant name for example. Only visible in the Pushpay Admin portal and the API.
Additional Data ad Text ad=%7B%22name%22%3A%22some%20name%22%7D Can be used for storing the information associated with the payment, such as participant name for example. Must be JSON formatted, and is only available via the API.
Redirect URL ru Text ru=Brand%20New%20Redirect A pre-approved token, linked to a URL that has been added or approved by Pushpay (see Adding Redirect URLs below). The URL must be HTTPS.

Configuring Redirect URLs

A merchant admin can add additional redirect URLs at the end of the Preconfigured Giving Link experience. This will allow you to send the giver to a different redirect URL for funds or campaigns etc.

For third party integrators, we require using a single endpoint for a redirect URL. You can use the source reference to pass a unique identifier back with the redirect. This will allow you to dynamically update the redirect page with donation specific content.

The redirect URL will be appended with a payment token that can be used to reference the full payment details using a secure connection to the Pushpay API. A payment token will only be included if payment was successfully taken.

Value Notes
Payment Token Reference that can be used to retrieve further details on payments via Pushpay API.
Source Reference This can be any reference value, which will be passed back with a redirect URL as a query string parameter alongside the payment token.

e.g. Church provides Pushpay with a redirect URL landing page: https://mychurch.com/ppredirect (mychurch).

Then when constructing the Preconfigured Giving Link, you pass in the redirect code (mychurch) and source reference e.g. Https://pushpay.com/g/mychurch?a=20&fnd=1&up=14041234567&ru=mychurch&sr=campaign1

When the donor is redirected to https://mychurch.com/ppredirect, your page would need to store/parse out the payment token and source reference and redirect appropriately.

Adding Redirect URLs

  1. Log into your merchant portal and scroll down to Settings on the sidebar.

  2. Click on Settings and then on API settings.

  3. Go to Configure preconfigured redirects.

  4. Add or edit an existing URL.

  5. Finally add the Redirect Key and Redirect URL to be used for your Preconfigured Giving Links. Use the Redirect Key in the URL after ‘ru=’ in this example:
    https://pushpay.com/g/mychurch?a=20&fnd=1&up=14041234567&ru=Brand%20New%20Redirect&sr=campaign1

Note! If you are a third party developer looking to integrate with Pushpay, you will need to contact api@pushpay.com in order to have your global redirect URL whitelisted.

Retrieving Final Transaction Records

To confirm that transactions have been made and processed successfully, you should periodically poll the Pushpay API.

It may be desirable to pre-filter the results to reduce the size of the returned data. You could do this by specific fund and/or merchant listing. It is also possible to filter by date range using updatedFrom and updatedTo dates.

As well as providing the expected Pushpay data for these transaction records, the data will include the references for Donor ID and Transaction ID from the integrated ChMS (if your organization has one configured). This data may not be available immediately depending the synchronize schedule that Pushpay has with the ChMS in question. Use of the updatedOn date when retrieving transaction records can help with identifying records that have been updated once synchronized with a ChMS.

The record of a single transaction could be updated several times after it is initially created; once when the record is updated with data from a ChMS; and a second time when the transaction is settled. Card transactions are generally deposited into the merchant’s account ~2 business days after the transaction, while ACH transactions clear ~4 business days after the transaction.

For more details on how to successfully synchronize transactions with Pushpay, see Payments Synchronization Guidance.

API Usage Examples

Examples of API requests and responses can be found here: https://pushpay.io/docs/operations/payments#get__v1_merchant_merchantKey_payments