Introduction Pushpay excels at making giving easy for your attendees. With the Pushpay Rock integration that simplicity now extends all the way back to your church management system. After a quick setup, transactions will automatically be downloaded right to your Rock database.

Let’s get started!

Setup IMPORTANT: Before getting started it is important that your site be configured to use SSL (website encryption). Not only is this needed for security, but it’s also a best practice for all modern websites.

After installing the Pushpay Integration plugin from the Rock Shop, your Rock instance will have a couple new options under Admin Tools > Installed Plugins.

The first is ‘Pushpay Accounts’. This option is used to configure the integration and determines how Pushpay transactions are downloaded and processed by Rock. The second is ‘Pushpay Payer Keys’. This option is used to change how the Pushpay users are linked to Rock users.

Getting Started Setting up the Pushpay Plugin is easy but there are a few steps to follow:

1. Account Authorization 2. Configuration of Account 3. Configuration of Merchant Listings 4. Matching Pushpay Funds to Financial Accounts in Rock 5. Configure Payment Types

Step 1: Account Authorization 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 under Admin Tools > Installed Plugins:

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. If you are already using Pushpay, you have the option to request these values from Pushpay, or you have the option of registering for a new Pushpay account.

Once you have entered the API information and clicked “Save,” you will 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 authorizing, you'll be redirected back to the account list in Rock, and you will see your account listed. There, step one is done! See that was easy…

Step 2: Configure Account Now it’s time to configure the account in Rock.

There are several settings on the account that will affect what transactions are downloaded from Pushpay and how those transactions are grouped into batches. Click the edit (pencil) icon to view these settings.

Here’s an overview of the options on the first tab. Pay special attention to the “Limit Download to Settled Transactions” and the “Cutover Date” options as those will control what transactions are downloaded by the plugin:

Account Name: This can be used to create a friendly name for your account. This is helpful if you have more than one Pushpay account that you integrate with.

API Client Id/Secret: These are the same values you entered when creating the account and will likely not need to be changed.

Active: This flag can be used to enable/disable the account. If the account is not active, transactions will not be downloaded for this account from Pushpay.

Limit Download to Settled Transactions: This option is selected by default and will result in transactions only being downloaded from Pushpay after they have settled. If you would like to see transactions in Rock as soon as possible and not wait for them to settle, you can unselect this option.

Cutover Date: If a value is entered in this field any transactions that occurred prior to this date will not be downloaded into Rock by the plugin.

Make sure to select the “Advanced Settings” tab also. It includes several options that control how transactions are grouped into batches.

These settings affect how the downloaded transactions are grouped into batches. For each transaction, a combination of batch date, campus and name will be determined. If an existing open batch already exists with those same values, the transaction will be added to that existing batch. If an open batch does not exist with those values, a new batch will be created with those values (transactions will never be added to a closed batch).

These settings control if and how the date, campus, and name are determined for each transaction.

Batch by Transaction Date. If this option is selected, the batch date will be the date of the transaction. If this option is not selected, the transaction date will be ignored, and transactions will only be grouped by campus (optional) and batch name.

Batch by Campus: If this option is selected, the batch campus will be determined by evaluating the financial account that the transaction is associated with. If that account is configured in Rock for a specific campus, the batch will also be for that campus.

Batch by Name: Transactions will always be grouped by name, and you have control over how the name is determined. It will consist of three parts.

o Prefix: This is a setting on the “Download Pushpay Payments” job and defaults to “Pushpay”. Because it is a job setting, it will affect all downloaded transactions regardless of account and/or merchant configurations.

o Currency/Credit Card Type: This is an abbreviation representing the currency or credit card type of the transaction. This is the only part you can enable or disable from this

account settings page. Select the Include Currency Type in Batch Name option to include it.

o Suffix: This a merchant Specific setting that can be used to set unique batch names specific to each merchant. The value is based on the payment item downloaded from Pushpay and will default to the item’s Settlement name. See the Batch Name Suffix setting in the Configure Merchant Listings section below for more details on how to configure this value.

Once the batch has been determined for a transaction there’s an additional setting that controls what to do with that transaction if it had previously been downloaded and already added to a different batch:

Move Updated Transactions: When a transaction is updated by Pushpay (i.e. it settles), the calculated batch name may be different than the transaction’s original calculated batch name. If you enable this option, the transaction will be moved to a new batch based on its new batch name and removed from the previous batch. This only affects transactions that are in an open batch. If the updated transaction is in a batch that has already been closed, it will not be moved.

Step 3: Configure Merchant Listings After confirming the account settings, you will need to configure each merchant listing for the account. Each account will have at least one merchant listing, but you could have several depending on how your account was originally setup and configured with Pushpay.

Note: If you do not see any merchant accounts listed, there may be an issue with your Rock server not being able to communicate with the Pushpay API due to it not supporting or using the TLS 1.2 security protocol. See Appendix B for instructions on how to ensure your server supports the TLS 1.2 protocol.

One of the features of merchant listings in Pushpay is the ability to select different funds that are available for people to give to when selecting your listing from their Pushpay app. For example, if your organization has multiple campuses, you may have a different merchant listing for each campus with a different set of funds for each of those listings. You might also just have one merchant listing that

includes a custom campus field that people can select from (in addition to the fund). Both of these multi-campus configurations in Pushpay are supported by the Rock Pushpay integration. And... if you only have one campus, don't worry, it supports that too.

To start configuring your merchant listing(s), click the account name from the account list. This will display a list of the merchant listings associated with your account.

To configure the merchant listing, click the edit (pencil) icon.

This screen is used to set the default Rock account for your merchant listing, configure how batch names are created, configure the transaction type that should be used, and to select the optional Pushpay field that contains a “memo” value.

Default Account: A default Rock account needs to be selected for each merchant listing. Any transaction that is downloaded from Pushpay with a fund 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.

Transaction Type: Normally, transactions downloaded from Pushpay and added to Rock would have a transaction type of “Contribution”, but you can change this for any merchant so that transactions downloaded from that merchant have a different transaction type (i.e. “Event Registration”).

Pushpay Field for Memo: If your merchant listing includes a field for users to enter a memo, you can select that field here (if a field is found with the name of "Memo," it will automatically be selected). The value that is entered by a person into this field when giving through Pushpay will be included in the summary field of the Rock transaction that gets created when your transactions are downloaded to Rock from Pushpay.

Batch Name Suffix: This is an optional Lava template that will be used to append a value to the end of the Rock batch name used for each transaction downloaded from Pushpay. The default value uses the Pushpay settlement name if it exists, otherwise it will be blank. To have transactions from each merchant listing be added to different batches in Rock, make sure this value is different for each merchant. For example the following value would add “Listing A” to the batch name (along with Pushpay’s settlement batch name): Listing A {% if Item.Settlement and Item.Settlement.Name != '' %} - {{ Item.Settlement.Name }}{% endif %}

See the “Transaction Processing / Batch Names” section below for more details on how batch names are created, and Appendix A: Payment Item for details of what’s available to your Lava.

Once you’ve configured the merchant listing, you will then need to map each of your organization’s Pushpay funds to an account in Rock.

Step 4: Configure Funds In Pushpay, your organization will have one or more funds that users can choose from when making a gift through a merchant listing. Each of these funds needs be mapped to an account in Rock. Not all organizational funds may currently be active for a merchant, but they will still need to be mapped so that if there are historical transactions for the fund, they can be associated to the correct account in Rock. To configure the funds for a merchant listing, click the name of the merchant listing. This will display all of the Pushpay funds for your organization.

To configure a fund, click the edit (pencil) icon. The fund configuration screen will then provide a way of associating the Pushpay fund to the correct Rock account(s). You'll be able to associate the Pushpay fund to one account in Rock, or optionally to different accounts based on each campus that has been defined in Pushpay.

Use one account for a fund: If you don't have multiple campuses, or your Pushpay account supports multiple campuses through multiple merchant listings (rather than a campus field), or If you'd just like the selected fund to be associated with one Rock account regardless of campus, select the 'Use one account for this fund' option, and then pick the Rock financial account that you'd like it to be mapped to.

Select account by campus: You can optionally associate each fund to a different Rock account based on each Pushpay campus. Select the 'Select accounts by campus' option, and then pick the Rock financial account that you'd like this fund to be mapped to for each campus.

Step 5: Configure Payment Types Pushpay has “Payment Types,” and Rock has “Currency Types.” These are close to the same thing, but not exactly. No worry’s though, the plugin allows us to map one to the other. This is done on the

Pushpay Payment Gateway. Navigate to Admin Tools > System Settings > Financial Gateways and select the “Pushpay” gateway.

Notice the Payment Type Mapping:

For each Pushpay payment type (left column), you can select the Rock currency type (right column). If you need to, you can also add new payment types and map them to a currency type. If a transaction is downloaded from Pushpay with a payment type not on this list, it will use the “Unknown” currency type in Rock.

Updating Configuration If your Pushpay account is ever updated, for example a new merchant listing is added to your account, or new fund or campus field values are added, you will want to refresh the settings for your Rock Pushpay integration. From the account list page, click the Refresh icon on the account you want to update.

This will update any merchant listing, funds, and campus values associated with those listings. You'll then want to repeat steps 2 and 3 above to make sure any new listings and funds have been setup correctly.

Downloading Transactions Now that your setup is complete we’re ready to get down to the business of downloading transactions.

Manual Downloading 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.

Transaction Processing When transactions are downloaded from Pushpay there are several things to consider.

Person Matching Each transaction downloaded from Pushpay includes a payer key that is unique to the Pushpay login or device that was used to create the payment. The Plugin will try all the following ways to find the correct person in Rock to associate the transaction with:

1. Existing Payer Key: If an existing person has already been associated to that key, it will associate the new transaction with that same person in Rock.

2. Name and Email/Phone Number: If a match on the payer key is not found, Rock will evaluate the name, email, and mobile phone number from the Pushpay transaction and look for the first person in Rock who matches that criteria by looking in the following order:

a. An adult with the same name, email and mobile phone number. b. A child with the same name, email and matching mobile phone number. c. An adult with the same name, email, and phone number of any type. d. A child with the same name, email and phone number of any type. e. An adult with the same name and mobile phone number. f. An adult with the same name and any matching phone number. g. An adult with the same name and email. h. A child with the same name and mobile phone number. i. A child with the same name and any matching phone number. j. A child with the same name and email.

3. Mobile Phone Number: If a match could not be made on payer key or by using the name and the email/phone, Rock will then look for a single adult in Rock with the same mobile phone number. If there’s only one person, it will associate the transaction with that person.

4. Any Phone Number: Rock will then look for a single adult with any phone number that matches the Pushpay phone number. If it finds just one adult, it will associate the transaction with that person.

5. Create New Person: If a match was not found using the payer key, or by matching name, email and phone number, a new person record will be created in Rock.

Whether a match was found, or a new person was created, the payer key is then associated with that person so that all future transactions with that key will be matched to the same person (first method in list above). This association will persist even if a person is merged in Rock with another person.

Fixing a Match Sometimes the payer key may get associated to the wrong person. For example, if a phone number was associated to the wrong person in Rock when the first transaction for that number was downloaded. This is when you use the “Pushpay Payer Keys” option under Admin Tools > Installed Plugins.

This block will list all the Pushpay Payer Keys and the person it is associated with.

You can filter the list by the Payer Key or by the person. To associate a key with a different person, use the filter to find the incorrect person that the key is associated with. Once you’ve found the key, Edit the row and select the correct person. That’s all it takes. From then on, anytime a transaction with that key is downloaded, it will get associated to the correct person.

Declines/Reversals Any transaction that has a status in Pushpay of “Success” or “Processing” may be downloaded and added to Rock as soon as the transaction is created. (if configured to do so on the Account configuration). 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.

Recurring Transactions When the Pushpay plugin was installed, it created a new attribute on Rock’s Financial Transaction Entity. That sounds complicated, but all it means is that you’ll see a new “Pushpay Recurring Txn” column whenever you’re looking at a list of transactions. Transactions that are downloaded from Pushpay and part of a Pushpay recurring transaction will have a check-mark in this new column:

Payment Token When Transactions are added to Rock, the Pushpay Transaction Id is saved to the “Transaction Code” field on Rock’s Transaction record and that value is always visible in Rock. The plugin will also save the Pushpay Payment Token value to the “Foreign Key” field in Rock. By default, this field is not displayed. If you need access to this value, the Transaction List block has a “Show Foreign Key” setting. If that setting is enabled, the block will display the Foreign Key value:

Appendix A: Item Model The Merchant configuration in Rock allows you to use a Lava template when setting the Batch Name Suffix property, and whenever you use Lava it’s helpful to know what will be passed to your Lava. Below is the structure of the “Item” object that will be passed to the Batch Name Suffix Lava template.

{ "Status": null, "RecurringPaymentToken": null, "RefundedBy": { "TransactionId": null, "PaymentToken": null, "AvailableKeys": [ "TransactionId", "PaymentToken" ] }, "RefundFor": { "TransactionId": null, "PaymentToken": null, "AvailableKeys": [ "TransactionId", "PaymentToken" ] }, "Settlement": { "Key": null, "Name": null, "EstimatedDepositDate": "0001-01-01T00:00:00", "AvailableKeys": [ "Key", "Name", "EstimatedDepositDate" ] }, "TransactionId": 0, "PaymentToken": null, "Amount": { "Amount": 0.0, "Currency": null, "AvailableKeys": [ "Amount", "Currency" ] }, "Payer": { "Key": null, "EmailAddress": null, "EmailAddressVerified": false, "MobileNumber": null, "MobileNumberVerified": false, "FullName": null, "FirstName": null, "LastName": null, "Address": { "Country": null, "AvailableKeys": [ "Country" ]

}, "Role": null, "PayerType": null, "_links": null, "AvailableKeys": [ "Key", "EmailAddress", "EmailAddressVerified", "MobileNumber", "MobileNumberVerified", "FullName", "FirstName", "LastName", "Address", "Role", "PayerType", "Links" ] }, "Recipient": { "Key": null, "Name": null, "Role": null, "AvailableKeys": [ "Key", "Name", "Role" ] }, "Fields": [ { "Key": 0, "Value": null, "Label": null, "AvailableKeys": [ "Key", "Value", "Label" ] } ], "CreatedOn": "0001-01-01T00:00:00", "UpdatedOn": "0001-01-01T00:00:00", "PaymentMethodtype": null, "Source": null, "Card": { "Reference": null, "Brand": null, "AvailableKeys": [ "Reference", "Brand" ] }, "Account": { "RoutingNumber": null, "Reference": null, "BankName": null, "AccountName": null, "AccountType": null, "AvailableKeys": [ "RoutingNumber",

"Reference", "BankName", "AccountName", "AccountType" ] }, "Campus": { "Name": null, "Key": null, "AvailableKeys": [ "Name", "Key" ] }, "IpAddress": null, "_links": null, "AvailableKeys": [ "Status", "RecurringPaymentToken", "RefundedBy", "RefundFor", "Settlement", "TransactionId", "PaymentToken", "Amount", "Payer", "Recipient", "Fields", "CreatedOn", "UpdatedOn", "PaymentMethodtype", "Source", "Card", "Account", "Campus", "IpAddress", "Links" ] }

Appendix B: TLS 1.2 Support The Pushpay API requires that all requests are made using the TLS 1.2 security protocol. Newer operating systems will use this protocol by default, but if your Rock server is running on an older operating system (Windows Server 2012 for example), you will need to adjust registry settings so that the outbound API requests from your server use the correct TLS 1.2 protocol.

If your server is not configured correctly, the following exception will get logged by Rock each time that the plugin attempts to communicate with Pushpay:

Unexpected ApiGet Error. Status Code: 0; Response Status: Error; Error Message: The request was aborted: Could not create SSL/TLS secure channel.; Content:

The easiest way to make the correct registry updates, is to use the IIS Crypto tool from Nartac Software. This utility can be found at: https://www.nartac.com/Products/IISCrypto.

When running the utility (from your Rock server). Click the “Best Practices” button to select the correct protocols and ciphers. Make sure the “Set Client Side Protocols” checkbox is selected, then click “Apply”. This will make the needed updates to the registry settings on your server. You will also then need to reboot the server. The server will then be able to communicate with Pushpay’s API using the correct protocol.