Implementing the Payroll Feed Extension requires strategic collaboration between your organization and Bonterra’s CyberGrants Implementation team. Following Bonterra’s approved implementation methodology is critical to avoid unexpected system behavior, prevent data loss, and ensure eligibility for future product enhancements. 

Deviating from this methodology may result in additional costs, which are not included in the scope of the extension. Development cannot begin until all required inputs are received and approved. 

The following steps will guide you through the implementation process for this extension, from early planning through testing and post-implementation best practices. 

Pre-implementation planning 

Step 1: Define your campaign structure and business requirements 

• Decide whether your payroll program will operate as a 'Closed Campaign' (limited giving window) or 'Open Campaign' (year-round).
• Determine if the program will support both recurring and one-time payroll pledges.
• Identify how frequently deductions will be processed (weekly, bi-weekly, semi-monthly, or monthly).
• Confirm whether pledges will be processed in U.S. dollars, Canadian dollars, or both (NOTE: these must be sent on separate files).
• Establish your program’s start dates, rollover dates (for Closed Campaigns), and file delivery schedule. 

Step 2: Confirm technical and data transfer requirements 

• Ensure your payroll system can send and receive flat files via Secure File Transfer Protocol (SFTP).
• Confirm ability to format files using CyberGrants’ specifications (Header, Detail, and Trailer rows).
• Define a unique Deduction Code for each proposal type (e.g., “R” for recurring, “O” for one-time; “CR”/“CO” for Canadian equivalents).
• Confirm that all deduction amounts will be fixed dollar values (percentage-based programs are not supported).
• Ensure that only employees with payroll activity (i.e., who received a paycheck) will be included in the inbound file. 

Step 3: Coordinate internal roles and responsibilities 

• Assign a dedicated payroll representative to collaborate with Bonterra throughout the process.
• Ensure IT resources are available for SFTP setup, secure access, and file validation.
• Confirm participation in end-to-end testing, with staff available to receive and validate test files. 

Step 4: Submit all necessary credentials and sample files 

• Provide transmission details and SFTP credentials to CyberGrants.
• Submit valid outbound and inbound file samples that match the CyberGrants specification, including:
  • Proper formatting of employee IDs, dates, decimal values, and currency codes.
  • Presence of Header and Trailer records.
• Confirm the use of CyberGrants Disbursement Solution (CGDS), which is required for payroll feed implementation. 

Implementation process 

The following steps detail the full implementation process, including development, testing, and deployment. 

Step 5: Finalize specifications 

• Review and confirm CyberGrants’ standardized file layout and naming conventions.
• Validate your Deduction Codes and ensure they are mapped correctly to each Proposal Type.
• Agree on pledge rollover behavior (for Closed Campaigns) and initial file transmission timing. 

Step 6: Configure your system in CyberGrants 

• Set up Proposal Types within the CyberGrants system for each payroll giving program.
• Define default start dates for pledges and configure the recurring schedule for outbound and inbound file transmissions. 
• For Closed Campaigns, schedule the system to automatically close pledges and clone them as pending before the next campaign. 

Step 7: Conduct end-to-end testing 

Bonterra requires three successful end-to-end test cycles before deployment. 

Each test cycle must include: 

1. CyberGrants sends an outbound file with employee pledges.
2. Payroll processes the file and sends back an inbound file.
3. CyberGrants processes the inbound file and creates or updates gift and match records. 

Testing requirements: 

• Feedback files from CyberGrants must be returned by your team within 2 business days.
• Errors identified in test files must be remediated and resubmitted within 2 business days.
• Negative deduction amounts in inbound test files will be flagged and ignored.
• Any unmatched records (e.g., inbound deductions without corresponding pledges) will be excluded and flagged in the Inbound Error Report. 

Step 8: Conduct User Acceptance Testing (UAT) 

• Review gift creation, pledge rollover behavior, and match record generation using the test environment.
• Validate reporting accuracy and ensure business rules have been applied correctly.
• Provide written sign-off on the implementation. 

CyberGrants will not deploy any functionality to production without your formal approval. 

Step 9: Deploy to production 

• Once approved, the Payroll Feed Extension is moved to the live environment.
• Initial outbound and inbound file transmissions are monitored closely by CyberGrants.
• Records are reviewed for completeness, accuracy, and compliance with the agreed file structure. 

Post-implementation management

Step 10: Monitor file transmissions and system behavior 

• Review each file delivery for the expected format and delivery time.
• Inspect Inbound Error Reports and act on flagged records.
• Track gift and match record creation based on inbound data. 

Step 11: Maintain pledge data integrity 

• Confirm employees have no more than one active pledge per proposal type at any time.
• Use CyberGrants to cancel outdated or inactive pledges.
• Ensure pledge modifications are made through CyberGrants, not directly in the payroll system, to avoid mismatches. 

Step 12: Manage annual rollover for closed campaigns 

• Before launching a new campaign cycle, configure CyberGrants to:
  • Close all active pledges from the previous cycle.
  • Clone these pledges as pending for the upcoming cycle.
  • Make them available in the employee UI once the campaign opens. 

Step 13: Understand change request and backout policies 

• Any changes to the payroll feed extension after go-live may incur additional costs.
• File backouts are only eligible before batching or payment and must be requested formally.
• Backouts and reprocessing efforts are billable and must be coordinated through your Implementation Project Manager. 

Step 14: Stay aligned with Bonterra’s extension policies 

• You may request one scope-bound change per calendar year.
• Major changes or additional programs may require new project scoping or extension purchases.
• Always coordinate planned modifications through your Implementation Project Manager. 

What else do you need help with?

• What is the Payroll Feed Extension?

Not what you're looking for? Navigate to Payroll Feed Extension Overview

Looking for training?

Explore this feature at your own pace - access training video content or watch a recorded webinar by clicking the link below.