This article is designed to help you configure and set up Pushpay and Rock RMS to allow transaction information to be passed directly from Pushpay into Rock RMS.
What is it?
Churches who are using Rock RMS can have Pushpay integrate with it. When payments are made through Pushpay to your organization, Rock will automatically import the corresponding transaction data from Pushpay.
How does it work?
The Pushpay/Rock integrations works in real time behind the scenes to make the integration experience seamless. Once enabled, Rock imports every payment and automatically creates the necessary contribution records within your Rock account.
When transactions are imported, Rock will attempt to match them up to the appropriate person using a combination of name and email address. If Rock can’t find a donor match based on name and email address, a new person will be created.
Step 1: Setting up the Integration
After installing the Pushpay Integration plugin from the Rock Shop, your Rock instance will have a new option under ‘Admin Tools > Installed Plugins’ called ‘Pushpay Accounts’. This option is used to configure the integration and determines how Pushpay transactions are downloaded and processed by Rock.
The setup is done in 3 easy steps:
Configuration of Merchant Listings
Matching Funds to Accounts
Before Rock can communicate with Pushpay, information about your Pushpay account needs to be added to Rock. This is done using the new ‘Pushpay Accounts’ option.
The first time you view this page, Rock will ask for the API Client ID and Secret so that it can access your Pushpay account. To request these values, simply click on the "Existing Pushpay Customer" button and a request will be generated for you. After the request has been validated, one of our developers will securely send you the API credentials.
Once you have entered the API information and clicked “Save,” you will immediately be redirected to Pushpay in order to authorize Rock to have access to your Pushpay account. If you are not currently logged into Pushpay, you will first be asked to do so.
Once you have logged in with an administrator account, you will be asked to authorize Rock to access your Pushpay account.
After you’ve authorized Rock to access your Pushpay account, you will be redirected back to the account list in Rock.
Configure Merchant Listings
Now you’ll need to configure each of your merchant listings for your account. The Merchant Listings column will indicate how many of the merchant listings for your account have been completely configured in Rock. Typically you will have a different merchant listing for each of your campuses.
To configure the merchant listings, click the account name from the account list. This will display a list of each merchant associated with your account.
To configure a merchant listing, click the edit (pencil) icon.
The merchant listing configuration screen provides a way of associating which Pushpay field contains the fund/account selection and the default account that transactions should be applied to:
Merchant Listing Field for Funds: Each merchant listing in Pushpay can have one or more custom fields configured. One of these fields is used to indicate the fund/account that a person would like their gift to go towards. Typically, this is known as "Fund" or "Giving Type." Rock will query your merchant listing configuration to get the list of custom fields. Select which of these fields is used by Pushpay to select the fund/account (If Rock finds one with a name of “Fund” it will automatically default to using that field).
Default Account: A default Rock account needs to be selected for each Merchant Listing. Any transaction that is downloaded from Pushpay with a fund/account value that has not been specifically mapped to a Rock account will be applied towards this account. Transactions cannot be downloaded for a merchant listing without a default account configured.
Active: Flag indicating if this merchant listing is active. Transactions will not be downloaded for any merchant listing that is not active
Once you’ve configured the reference field for funds and the default account, you will need to map each of that field’s values to an account in Rock. The Funds column indicates how many of the funds have been mapped to a Rock account.
To configure the funds for a merchant listing, click the name of the merchant listing. This will display a list of each of the values that were available for the selected reference field.
To configure a fund, click the edit icon.
The fund configuration screen provides a way of associating a Pushpay field value to the correct Rock account:
- Rock Financial Account: The Rock account that transactions with this field value should be applied to.
Once all the funds have been associated with a Rock account you are now ready to download Pushpay transactions.
Step 2: Downloading Transactions
Now that this setup is complete we’re ready to get down to the business of downloading transactions.
Note: If you have already imported historical Pushpay transactions into Rock from another source (i.e. your previous church management system), please consult us at email@example.com before configuring your first manual download from the Pushpay plugin to ensure no discrepancies are created between the two systems.
There are two ways that transactions can be downloaded from Pushpay. The first is to download them manually using the account’s Merchant Listing page.
Clicking the download icon for a merchant listing will display a dialog that you can use to enter the date range that you’d like to download transactions for.
Once you enter a date range and click download, Rock will search for any Pushpay transactions that were created or updated during that date range and download them to Rock.
Configuring Daily Downloads
The second and preferred way of downloading transactions is through a new Rock job that was added by the plugin. To configure this job use ‘Admin Tools > System Settings > Jobs Administration’ and select the ‘Download Pushpay Payments’ job.
By default this job is scheduled to run every morning at 2:00 am. It also has some settings that can be configured:
Batch Name Prefix: The prefix to use when determining batch name that transactions are added to (see the Batch Names section below).
Default Campus: The default campus to use for any new people that are added to Rock by the download (see the Person Matching section below).
Connection Status: The Rock connection status to use for any new people that are added to Rock.
Record Status: The Rock record status to use for any new people that are added to Rock.
Days Back: The number of days back to look for transactions. Any Pushpay transactions that have been created or updated since then and the time job is run will be downloaded.
Each transaction downloaded includes a payer key that is unique to the Pushpay login or device that was used to create the payment. Rock will look for a person that has already been associated to that key and associate the new transaction with that person in Rock. If a match on the key is not found, Rock will evaluate the first name, last name, and email associated with the payment and search for a person in Rock with the same values. If one (and only one) match is found, the matching person is associated with the transaction. If a single match is not found, a new person will be created in Rock and associated with the payment. The new person’s connection status is determined from the job setting on the daily download, or the block setting on the manual download. Whether a match was found or a new person is created, the payer key is then associated with that person so that future transaction download can be matched on the key. The person/key associations will persist even if a person is merged in Rock with another person.
When users make a payment in Pushpay, that transaction could take several days to completely process and settle. For example ACH could take up to 5 days to settle. However, in order for you to have a better indication of daily gift amounts, the plugin will still download those transactions even if they are still being processed by Pushpay.
When these transactions are downloaded from Pushpay, they are added to a batch in Rock. The name of the batch is determined by a combination of the prefix specified by the download job setting (or block setting when downloading manually), the currency type (credit card/ach) of the transaction, and whether the transaction has settled or not.
The default prefix is “Pushpay,” so all batch names will usually begin with either “Pushpay ACH” or “Pushpay Credit Card.” The exception to that is if the type of credit card for the transaction has been configured in Rock to have a different Batch Name Suffix. In this case the batch name would use that suffix instead of “Credit Card”. Transactions that have settled, will be added to a batch that has the Pushpay settlement name appended to its name. Here’s some examples:
a) A credit card transaction is downloaded and has not yet settled. It will be added to a batch name of ‘Pushpay Credit Card.’
b) An ACH transaction is downloaded that has settled with a settlement name of ‘ACH20160119’. It will be added to a batch name of ‘Pushpay ACH – ACH20160119’.
c) A Visa card transaction is downloaded that has settled with a settlement name of ‘FD20160120’ AND the Visa credit card type in the Rock ‘Credit Card Type’ defined type has been configured with a Batch Name Suffix of ‘VMD’. It will be added to a batch name of ‘Pushpay VMD – FD20160120’.
Note: If a batch with the correct name and same date of the transaction’s date does not yet exist, the plugin will create a new batch.
When a transaction finishes processing and is updated by Pushpay to include settlement information, that transaction will be moved from the “unsettled” batch in Rock to a new batch that includes the settlement name. This provides a way of matching/reconciling Rock batches with their corresponding batch/settlement information in Pushpay. This move will only occur if the original batch has a status of ‘Open’ or ‘Pending’. ‘Closed’ batches are assumed to be locked and will not be updated.
Batch Name Suffix
Each credit card type in Rock can be configured with a "Batch Name Suffix": http://urlForYourRockInstance/page/119?definedTypeId=11
This is used to group transactions with those credit card types into unique batches. By default, all of the Visa, MasterCard, and Discover transactions will be grouped into the "VMD" batch and any other credit card transactions are getting placed into the "CreditCard" batch.
Unless your organization is processing a significant amount of American Express transactions such that you were required to set up a separate merchant account with them, we recommend you remove the "VMD" batch name suffix from those three credit card types, and then all credit card transactions will get put into the "CreditCard" batch.
Batches with Transactions across Multiple Days
Batches in Rock have start and end date/times. When each transaction is downloaded, the transaction date is evaluated, and it is added to the batch with the correct name, and who's start/end date/times span the transaction date. If an open batch is not found, a new batch is created. When a new batch needs to be created, the start/end times will always span a 24 hour period. By default this is 12:00am – 12:00am.
Therefore, if there are batches with transactions that span more than one day, these will not be grouped together in Rock. However, they will contain the same batch name identifier from Pushpay (e.g. ACH20160928) and the transactions can easily be moved from one batch to another.
Any transaction that has a status in Pushpay of “Success” or “Processing” is downloaded and added to Rock as soon as the transaction is created. (“processing” transactions are included so that you can have an immediate indication of the number and amount of transactions that occurred during a specific time period). Some of those transactions may later be declined or reversed. If this happens an additional offsetting negative transaction is created in Rock so that the net amount for the transaction is zero.