What is the Payroll Feed Extension?

The Payroll Feed standard extension automates and manages payroll deduction processing through a secure, two-way file-based data exchange. This integration enables employees to pledge donations directly from their paychecks and ensures the accurate transmission and reconciliation of deduction data between Bonterra’s CyberGrants and the customer’s payroll system. 

It facilitates the end-to-end process of outbound pledge data delivery from CyberGrants to your payroll system and inbound deduction confirmation data back to CyberGrants. Using these confirmations, the system creates or updates Employee Giving gift records and optional company Match records, ensuring real-time visibility and alignment with actual contributions. 

Important terms and definitions 

• Flat file – A delimited file sent via Secure File Transfer Protocol (SFTP).
• SFTP location – The secure server directory where files are exchanged between CyberGrants and your payroll system.
• Proposal type – A specific giving program configuration (e.g., payroll giving) used to present pledge forms to employees.
• Match – Company contributions that are made in response to employee donations, following defined matching rules. 

How it works 

The Payroll Feed Extension establishes a two-way data exchange between CyberGrants and your payroll platform: 

Pledge behavior and lifecycle 

• New pledge (one-time): Sent in outbound file → marked as Closed.
• New pledge (recurring): Sent in outbound file → marked as Active.
• Edit recurring pledge:
  • The original pledge is marked Cancelled.
  • The new Pending pledge is created.
  • If the total amount changes → a new pledge is included in the outbound file.
  • If the total remains the same (but organization allocations change) → no change appears in the outbound file.
• Cancel pledge:
  • Pledge is marked Cancelled.
  • Outbound file sends a $0 deduction to stop payroll deductions. 

File formats 

Outbound file:

Text-delimited file sent via SFTP. Each record includes the following and should be kept in this specific order: 

• Header row (H): File metadata
• Detail rows (D): One per pledge
  • Record type
  • Employee ID
  • Deduction code ("R", "O" for U.S.; "CR", "CO" for Canada)
  • Deduction start date (MM/DD/YYYY)
  • Deduction amount (with two decimals)
• Trailer row (T):
  • Total record count
  • Total deduction amount
  • Currency code (USD or CAD) 

Separate files are generated for each currency type. 

Inbound file:

Each record includes the following and should be in the same structure as the outbound file, but confirm actual deductions: 

• Detail rows (D):
  • Record type
  • Employee ID
  • Deduction code
  • Deduction date
  • Amount deducted
• Trailer row (T):
  • Total record count
  • Total deduction amount
  • Currency code 

Match record handling 

• Match records are optional and only generated after a confirmed deduction is received via the inbound file.
• The match amount is calculated based on the actual deduction, not the pledged amount.
• Partial matches are not supported – the full deduction must qualify for a match. 

Validation and error handling 

CyberGrants includes built-in validations to ensure data integrity: 

• Negative deductions:
  • Ignored by the system
  • Flagged in the Inbound Error Report
  • Communicated back to payroll via the customer’s designated distribution list
• Missing pledges: 
  • If a deduction is received for an employee without a corresponding pledge, the record is ignored and flagged. 
• Payroll-only modifications: 
  • If the payroll system modifies a pledge without a matching change in CyberGrants, discrepancies will occur in reporting. 
  • CyberGrants will still create gift records for the inbound amount. 
• Unreported cancellations: 
  • If an employee cancels their pledge only through payroll, CyberGrants will still consider the pledge active, which can cause reporting discrepancies. 

Assumptions and dependencies

• Employees can have one active pledge per proposal type, per pledge type (recurring or one-time).
• All deduction records must be initiated through CyberGrants.
• CyberGrants will create gift records for any donor appearing in the inbound file, regardless of employment status.
• All deduction values must be fixed-dollar amounts (no percentages).
• CyberGrants Disbursement Solution (CGDS) is required for payroll feed implementation.
• Files must be transferred via SFTP.
• Payroll must not send deductions for employees without an actual paycheck (e.g., those on unpaid leave).
• Separate files must be used for different currencies (USD/CAD).
• Deduction codes must be unique per proposal type.
• Backout of processed files is only allowed before batching or payment and may incur additional cost.
• Payroll must return test files within 2 business days.
• Errors must be corrected and returned within 2 business days to stay on schedule.
• Implementation cannot begin until:
  • Transmission credentials are received
  • Sample files (in approved format) are provided
  • Three successful test cycles have been completed

What else do you need help with?

• How do I implement 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.