NPSP Extension Guide

Technical Guide of Open NPSP Check Scanning Extension

NPSP Extension Introduction

The NPSP Extension for Payology Check Scanning allows for seamless configuration of the Check Scanning User Interface, Auto-Fill Class, and Post-Batch Closure processes. It can be used as an out-of-box option or can be configured post-installation.

Support Gift Types

The NPSP Extension, out-of-box provides organizations with the option to choose from the following gift types within the check scanning user interface.

 • New Pledge - Pledge with a specific future balance.
 • Planned Giving
 • Open-Ended Pledge - Pledge with no specified future balance.
 • One-Time Gift
 • Multipayment Pledge - Pledge which allows for monthly, quarterly, and annual payments.
 • One-Time Gift with Memorial
 • One-Time Gift with Honors
 • Matching Gift
 • Major Gift
 • Corporate Gift - Used for third-party gifts (i.e. one check for multiple organizations with multiple donors - also payroll deductions).

Payology Settings Object Changes

After installation of the NPSP Extension, the System Administrator should first adjust the newly created fields within the Payology Settings object. The fields which must be adjusted can be found below.

Field NameField TypeDescription
Major Gift AmountCurrencyUsed to transition a one-time gift to a major gift during the post-batch closure process.
Pledge Opp Record TypeTextThe record type which will be used when a Pledge Opportunity is created.
Planned Giving Record TypeTextThe record type which will be used when a Planned Giving Opportunity is created.
Open-ended Opp Pledge Record TypeTextThe record type which will be used when an Open-Ended Opportunity is created.
One Time Gift Opp Record TypeTextThe record type which will be used when a One-Time Gift Opportunity is created.
Multi Payment Pledge Opp Record TypeTextThe record type which will be used when a Multi-Payment Pledge Opportunity is created.
Memorial Opp Record TypeTextThe record type which will be used when a One-Time Gift with Memorial Opportunity is created.
Matching Gift Opp Record TypeTextThe record type which will be used when a Matching Gift Opportunity is created.
Major Gift Opp Record TypeTextThe record type which will be used when a Major Gift Opportunity is created.
Honor Opp Record TypeTextThe record type which will be used when a One-Time Gift with Honors Opportunity is created.
Corporate Gift Opp Record TypeTextThe record type which will be used when a Corporate Gift Opportunity is created.

Payology Scanning Value Object

As part of the installation of the NPSP Extension, an object named Payology Scanning Value is generated. This object is used to determine which opt-out reasons will be displayed within the check scanning user interface.

As the second step in the configuration process, the System Administrator should create a record within the object for each opt-out reason used within the organization (if any). The Payology Scanning Value object includes the following fields:

Field NameField TypeDescription
NameTextUsed to signify the short name of the opt-out reason.
TypePicklistSelect "opt-out reason".
DescriptionTextThe opt-out reason description which will be displayed on the check scanning user interface.

Check and Check Allocation Object Changes

Upon install of the NPSP Extension, changes will be made to both the Payology Lite Check and Check Allocation objects. Below you will find the fields added, their type and descriptions.

Check Object

Field NameField TypeDescription
Opt-Out ReasonLookup (Payology Scanning Value)The value of this field will be derived from an optional selection made by the user on the check scanning user interface (optout reason picklist field).
Opt-OutCheckboxThe opt-out checkbox will be selected (true) if the user has selected to opt-out the donor on the check scanning user interface. The Opt-Out reason will be required when opt-out is selected.
FundLookup (General Accounting Unit)The value of this field will be derived from a required selection made by the user on the check scanning user interface (fund autocomplete/picklist field).
Check Received DateDateThe value of this field will be derived from an optional selection made by the user on the check scanning user interface (check received date field).
CampaignLookup(Campaign)The value of this field will be derived from a required selection made by the user on the check scanning user interface (campaign autocomplete/picklist field).

Check Allocation Object

Field NameField TypeField Description
Soft Credit ContactLookup (Contact)The value of this field will be derived from a required selection made by the user on the check scanning user interface (soft credit contact autocomplete field) if "One Time Gift with Soft Credit" is selected as a Gift Type.
Soft Credit AmountCurrency(18, 0)The value of this field will be derived from a required entry made by the user on the check scanning user interface (soft credit amount currency field) if "One Time Gift with Soft Credit" is selected as a Gift Type.
Pledge FrequencyPicklist:
Monthly
Quarterly
Bi-Annual
Annual
The value of this field will be derived from a required selection made by the user on the check scanning user interface (Pledge Frequency picklist field) if "Multi-Payment Pledge" is selected as a Gift Type.
Pledge AmountCurrency (18, 0)The value of this field will be derived from a required entry made by the user on the check scanning user interface (Pledge Amount currency field) if "Multi-Payment Pledge" or "Pledge" is selected as a Gift Type.
PaymentLookup (Payment)The value of this field may be populated using one of the following two methods:
1) The creation of a Payment record triggered by a Check Allocation record whose Gift Type is a new donation (i.e. one time gift, pledge, etc.).
2) An existing Payment record (corresponds to open opportunity) selected by the user on the check scanning user interface under the Gift Type picklist field.
Payment AmountCurrency (12, 2)The value of this field will be derived if the user has selected an existing payment on the check scanning user interface under the Gift Type picklist field. It will only be used for validation purposes (i.e. check allocation amount cannot exceed payment amount).
OpportunityLookup (Opportunity)The value of this field may be populated using one of the following two methods:
1) The creation of an Opportunity record triggered by a Check Allocation record whose Gift Type is a new donation (i.e. one time gift, pledge, etc.).
2) An existing Opportunity record (corresponds to open opportunity) selected by the user on the check scanning user interface under the Gift Type picklist field.
Notification RecipientLookup (Contact)The value of this field will be derived from a required selection made by the user on the check scanning user interface (notification recipient autocomplete field) if "One Time Gift with Memorial" or "One Time Gift with Honors" is selected as a Gift Type.
Honoree/Memorial ContactLookup (Contact)The value of this field will be derived from a required selection made by the user on the check scanning user interface (Honoree/Memorial autocomplete field) if "One Time Gift with Memorial" or "One Time Gift with Honors" is selected as a Gift Type.
Gift TypePicklist:
One Time Gift
One Time Gift with Memorial
One Time Gift with Honorarium
One Time Gift with Soft Credit
Matching Gift
Open-ended Pledge
Pledge
Multi Payment Pledge
Corporate Gift
Planned Giving
The value of this field will be derived from a required selection made by the user on the check scanning user interface (Gift Type Picklist field).
Corporate ContactLookup (Contact)The value of this field will be derived from a required selection made by the user on the check scanning user interface (Corporate Contact autocomplete field) if "Corporate Gift" is selected as a Gift Type. Used commonly when receiving third party checks (i.e. Blackbaud, etc).
EmployerLookup (Account)The value of this field will be derived from a required selection made by the user on the check scanning user interface (Employer autocomplete field) if "Matching Gift" is selected as a Gift Type.
Amount of PaymentsNumber (18,0)The value of this field will be derived from a required entry made by the user on the check scanning user interface (Amount of Payment numeric field) if "Multi-Payment Pledge" is selected as a Gift Type.

Auto-Fill Class

The Auto-Fill Class installed as part of the NPSP Extension will:

  1. Prepopulate the Household/Donor field with previously selected data (i.e. if the same check - routing & account was associated with a donor).
  • AND -
  1. Prepopulate "One Time Gift" as the default Gift Type option on the Check Scanning User Interface if there are no pledged opportunities (open opps) which are associated with the Household/Donor selected by the check scanning user.
  2. Prefill the Check Allocation field with the Check Amount
  • AND -
  1. Prepopulate all open opportunities and their corresponding payments (if any) which are associated with the Household/Donor selected by the check scanning user from oldest to newest until reaching the full Check Amount.
  2. Prefill the Check Allocation field with the open opportunity or corresponding payment amount.
  3. Prepopulate "One Time Gift" as the Gift Type option on the Check Scanning User Interface if there are no pledged opportunities (open opps) remaining and the sum of all allocations is less than the Check Amount.
  4. Prefill the Check Allocation field for the One Time Gift with the remaining balance (check amount MINUS sum of Check Allocation amounts associated with pledged opportunities and their corresponding payments.

Opportunity and Payment Record Creation and/or Updates

Upon successful transmission of check items to the Payology Payment Gateway, the status of the check records will transition to "Pending Deposit". On status change, the NPSP extension will trigger the creation of Opportunity and Payment Records if new donation gift types (i.e. one time gift, pledge, one time gift with soft credit, etc) are selected. If existing opportunities and/or corresponding payments are selected as the gift type on the check scanning user interface, the NPSP extension will trigger an update to the Opportunity and/or Payment Record.

NPSP Extension Trigger Guide

Below you will find a list of records and field values that are inserted or updated dependent on the Gift Types selected by the check scanning user. Please note that the NPSP Extension is an open package and each record/field value can be updated accordingly.

One Time Gift (or Major Gift if over $X)

If a One-Time Gift is selected from the Gift Type picklist on the Check Scanning User Interface, the following will be triggered for each Check Allocation meeting criteria.

Opportunity Record Creation

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypeIf Check_Allocation.Amount < Payology_Settings_c.Major_Gift_Amount then Payology_Settings_c.One_Time_Gift_Opp_Record_Type else Payology_Settings_c.Major_Gift_Opp_Record_Type
AccountCheck.Account
ContactCheck.Contact
AmountCheck_Allocation.Amount
Close DateTODAY
CampaignCheck.Campaign
Stage"Closed Won"
Probability"100%"
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Payment Record Creation

FieldValue
OpportunityNew.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

One Time Gift with Soft Credit

If a One-Time Gift with Soft Credit is selected from the Gift Type picklist on the Check Scanning User Interface, the following will be triggered for each Check Allocation meeting criteria.

Opportunity Record Creation

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypePayology_Settings_c.One_Time_Gift_Opp_Record_Type
AccountCheck.Account
ContactCheck.Contact
AmountCheck_Allocation.Amount
Close DateTODAY
CampaignCheck.Campaign
Stage"Closed Won"
Probability"100%"
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Payment Record Creation

FieldValue
OpportunityNew.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Partial Soft Credit Creation

FieldValue
ContactCheck_Allocation.Soft_Credit_Contact
OpportunityNew.Opportunity
Role Name"Soft Credit"
AmountCheck_Allocatiion.Soft_Credit_Amount

One Time Gift with Memorial or Honors

If a One-Time Gift with Memorial or Honors is selected from the Gift Type picklist on the Check Scanning User Interface, the following will be triggered for each Check Allocation meeting criteria.

Opportunity Record Creation

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypeIf Check_Allocation.Gift_Type = One Time Gift with Memorial then Payology_Settings_c.Memorial_Opp Record_Type

If Check_Allocation.Gift_Type = One Time Gift with Honors then Payology_Settings_c.Honor_Opp_Record_Type
AccountCheck.Account
ContactCheck.Contact
AmountCheck_Allocation.Amount
Close DateTODAY
CampaignCheck.Campaign
Stage"Closed Won"
Probability"100%"
Payment Method"Check"
Check/Reference NumberCheck.Check_Number
Tribute TypeIf Check_Allocation.Gift_Type = One Time Gift with Memorial then "Memorial"

If Check_Allocation.Gift_Type = One Time Gift with Honors then "Honors"
Honoree ContactCheck_Allocation.Honoree/Memorial Contact
Notification Recipient ContactCheck_Allocation.Notification_Recepient

Payment Record Creation

FieldValue
OpportunityNew.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Matching Gift

If a Matching Gift is selected from the Gift Type picklist on the Check Scanning User Interface, the below records will be triggered for each Check Allocation meeting criteria. Please note, unlike other gift types, Matching Gifts will create two opportunity records (1 paid opportunity for employee/donor and 1 unpaid opportunity for the employer/future donor). Only one paid payment record will be created for the employee.

Opportunity Record Creation - Donor Opportunity

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypePayology_Settings_c.Matching_Gift_Opp_Record_Type__c
AccountCheck.Account
ContactCheck.Contact
AmountCheck_Allocation.Amount
Close DateTODAY
CampaignCheck.Campaign
Stage"Closed Won"
Probability"100%"
Payment Method"Check"
Check/Reference NumberCheck.Check_Number
Matching Gift AccountCheck_Allocation.Employer
Matching Gift Status"Submitted"

Opportunity Record Creation - Employer Matched Opportunity

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypePayology_Settings_c.Matching_Gift_Opp_Record_Type__c
AccountCheck.Account
ContactCheck.Contact
AmountCheck_Allocation.Amount
Close DateTODAY
CampaignCheck.Campaign
Stage"Pledged"
Probability"100%"
Matching GiftNew.Employee.Opportunity

Payment Record Creation - Related to Donor Opportunity Only

FieldValue
OpportunityNew.Employee.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Existing Matching Gift

If an existing matching gift (i.e. open opportunity with matching gift) is selected from the Gift Type picklist on the Check Scanning User Interface, the below records will be triggered for each Check Allocation meeting criteria.

Opportunity Record Update - Related to Existing Employers Opportunity

FieldValue
Stage"Closed Won"
Payment MethodCheck
Check/Reference NumberCheck.Check_Number

Opportunity Record Update - Related to Existing Employees Opportunity

FieldValue
Matching Gift Status"Received"

Payment Record Creation - Related to Existing Employer Opportunity

FieldValue
OpportunityNew.Employer.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Open Ended Pledge

If a Open Ended Pledge is selected from the Gift Type picklist on the Check Scanning User Interface, the below records will be triggered for each Check Allocation meeting criteria. Please note, the opportunity created will not have an assigned amount as the amount is unknown to the organization.

Opportunity Record Creation

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypePayology_Settings_c.Open_ended_Opp_Pledge_Record_Type__c
AccountCheck.Account
ContactCheck.Contact
Close DateTODAY
CampaignCheck.Campaign
Stage"Pledged"
Probability"100%"
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Payment Record Creation

FieldValue
OpportunityNew.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Pledge

If a Pledge is selected from the Gift Type picklist on the Check Scanning User Interface, the below records will be triggered for each Check Allocation meeting criteria.

Opportunity Record Creation

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypePayology_Settings_c. Pledge_Opp_Record_Type__c
AccountCheck.Account
ContactCheck.Contact
AmountCheck_Allocation.Pledged_Amount
Close DateTODAY
CampaignCheck.Campaign
Stage"Pledged"
Probability"100%"
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Payment Record Creation

FieldValue
OpportunityNew.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Multi-Payment Pledge

If Multi-Payment Pledge is selected from the Gift Type picklist on the Check Scanning User Interface, the below records will be triggered for each Check Allocation meeting criteria. Please note, one paid Payment Record and multiple unpaid Payment Records will be created based on the schedule and frequency selected by the user.

Opportunity Record Creation

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypePayology_Settings_c. Multi_Payment_Pledge_Opp_Record_Type__c
AccountCheck.Account
ContactCheck.Contact
AmountCheck_Allocation.Pledged_Amount
Close DateTODAY
CampaignCheck.Campaign
Stage"Pledged"
Probability"100%"
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Payment Record Creation - Paid Record

FieldValue
OpportunityNew.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Payment Record Creation - Unpaid Record(s) for Future Scheduled Payments

FieldValue
OpportunityNew.Opportunity
Payment AmountCheck_Allocation.Pledge_Amount DIVIDED BY Check_Allocation.Amount_of_Payments
Paid"FALSE"
Payment DateIf Check_Allocation.PledgeFrequency = Monthly then Check.Check_Received_Date__c PLUS 30 days.

If Check_Allocation.PledgeFrequency = Quarterly then Check.Check_Received_Date_c PLUS 90 days.

If Check_Allocation.PledgeFrequency = Bi-Annual then Check.Check_Received_Date_c PLUS 180 days.

If Check_Allocation.PledgeFrequency = Bi-Annual then Check.Check_Received_Date_c PLUS 365 days.

Payment Record Creation - Final Unpaid Record(s) for Future Scheduled Payments (If Check_Allocation.Pledge_Amount DIVIDED by Check_Allocation.Amount_of_Payments is not EVEN)

FieldValue
OpportunityNew.Opportunity
Payment AmountX=(Check_Allocation.Pledge_Amount DIVIDED BY Check_Allocation.Amount_of_Payments) MULTIPLIED BY (Check_Allocation.Amount_of_Payments)

Check_Allocation.Pledge_Amount MINUS X = Y

(Check_Allocation.Pledge_Amount DIVIDED BY Check_Allocation.Amount_of_Payments) + Y
Paid"FALSE"
Payment DateIf Check_Allocation.PledgeFrequency = Monthly then Check.Check_Received_Date_c PLUS 30 days.

If Check_Allocation.PledgeFrequency = Quarterly then Check.Check_Received_Date_c PLUS 90 days.

If Check_Allocation.PledgeFrequency = Bi-Annual then Check.Check_Received_Date_c PLUS 180 days.

If Check_Allocation.PledgeFrequency = Bi-Annual then Check.Check_Received_Date_c PLUS 365 days.

Planned Giving

If a Planned Giving is selected from the Gift Type picklist on the Check Scanning User Interface, the following will be triggered for each Check Allocation meeting criteria.

Opportunity Record Creation

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypePayology_Settings_c.Planned_Giving_Record_Type__c
AccountCheck.Account
ContactCheck.Contact
AmountCheck_Allocation.Amount
Close DateTODAY
CampaignCheck.Campaign
Stage"Closed Won"
Probability"100%"
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Payment Record Creation

FieldValue
OpportunityNew.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Corporate Gift

If a Corporate Gift is selected from the Gift Type picklist on the Check Scanning User Interface, the following will be triggered for each Check Allocation meeting criteria.

Opportunity Record Creation

FieldValue
Opportunity NameCheck.Account + Check_Allocation.Amount + TODAY
Opportunity Record TypePayology_Settings_c.Corporate_Gift_Opp_Opp_Record_Type__c
AccountCheck.Account
ContactCheck_Allocation.Corporate_Contact
AmountCheck_Allocation.Amount
Close DateTODAY
CampaignCheck.Campaign
Stage"Closed Won"
Probability"100%"
Payment Method"Check"
Check/Reference NumberCheck.Check_Number

Payment Record Creation

FieldValue
OpportunityNew.Opportunity
Payment AmountCheck_Allocation.Amount
Paid"TRUE"
Payment DateIf Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NULL then TODAY or if Check.Check_Received_Date_c is NULL and Check_Batch.Received_Date_c is NOT NULL then Check_Batch.Received_Date_c else
Check.Check_Received_Date_c
Payment Method"Check"
Check/Reference NumberCheck.Check_Number