Salesforce Payments2Us to Synergetic Donation XML Converter

A Streamlit app for converting Salesforce Payments2Us donation exports into Synergetic-compatible XML for donation receipt import.

The app is designed for Finance users to upload a Salesforce CSV export, validate the data, review mapping results, and download a Synergetic XML file plus supporting exception and audit reports.

---

Purpose

This tool converts Salesforce donation payment data into the Synergetic Standard Receipt XML format.

For this process, each valid Salesforce row is converted into:

<Synergetic>
  <Receipt>
    <DonationPayment />
  </Receipt>
</Synergetic>

The app is specifically configured for donation payments, not general ledger-only receipts.

---

Key Features

• Upload a Salesforce Payments2Us CSV export.
• Validate mandatory fields before XML generation.
• Exclude records missing a Synergetic Community ID.
• Generate a separate exceptions CSV for excluded records.
• Map Salesforce credit card types to Synergetic luCreditCard codes.
• Enrich donation records with the correct Synergetic Fund and Appeal codes.
• Generate a Synergetic XML file without the XML declaration header, matching the sample Synergetic import format.
• Provide an audit CSV showing row-level conversion and mapping results.
• Provide Finance-friendly tabs for reviewing totals, exceptions, audit details, XML preview, and warnings.

---

Conversion Logic

The app converts valid Salesforce donation records into Synergetic XML using a Receipt parent node and a DonationPayment child node.

The conversion does not generate GLPayment nodes by default.

This is intentional because the Salesforce export represents donation data, and Synergetic donation imports require Fund and Appeal information to be supplied through the DonationPayment node.

---

Required Salesforce CSV Fields

The source CSV should include the following fields:

Salesforce Field	Purpose
Receipt No.	Used as the Synergetic ReceiptNumber
Bank Deposit Date	Used as the Synergetic receipt date
Contact Synergetic ID	Used to link the donation to the Synergetic community record
GL Receipt Name	Used as the receipt drawer/name
Name On Card	Used as the credit card name
Credit Card Type	Mapped to Synergetic credit card lookup codes
Total Amount Charged	Used as the receipt and donation amount
Banked Amount	Used for reconciliation checks
Merchant Facility: Merchant Facility Name	Used to derive Project, Fund, Appeal, Entity, and GL metadata

---

Missing Synergetic IDs

Rows without a Contact Synergetic ID are excluded from the XML output.

These records are written to an exceptions CSV with additional columns explaining the issue and required action.

Finance users should:

1. Download the exceptions CSV.
2. Create or locate the relevant Community record in Synergetic.
3. Populate the missing Contact Synergetic ID.
4. Re-upload the corrected exceptions CSV into the app.
5. Generate a new XML file for those corrected records.

This prevents invalid or unmatched donations from being imported into Synergetic.

---

Credit Card Mapping

Salesforce card type values are mapped to Synergetic pvCreditCard codes.

Salesforce Value	Synergetic Code
Visa	VISA
MasterCard	MCARD
American Express	AMEX

If an unknown credit card type is found, the app omits the optional CreditCardType field and records a warning.

---

Project, Fund and Appeal Mapping

The app uses the Salesforce Merchant Facility: Merchant Facility Name field to determine the correct Synergetic project metadata.

The Fund and Appeal values are written into the DonationPayment node as:

<DonationPayment
  ReceiptFundCode="..."
  ReceiptAppealCode="..."
/>

---

App Tabs

After uploading a CSV, the app displays several review tabs.

Project Totals

Shows included records summarised by project, entity, fund, appeal, and total amount.

Use this tab to reconcile the donation totals before downloading the XML.

Exceptions

Shows rows excluded from the XML.

Most commonly, this includes rows missing a Contact Synergetic ID.

Use this tab to download the exceptions CSV and fix missing Synergetic IDs.

Audit

Shows valid rows that were included in the XML, along with the derived Synergetic values.

Use this tab for row-level checking and audit support.

XML Preview

Shows a preview of the generated Synergetic XML.

The full XML can be downloaded using the XML download button.

Warnings

Shows non-blocking issues.

Warnings do not prevent XML generation, but they indicate values that were omitted, normalised, or require review.

---

Output Files

The app can generate three files:

Output	Description
Synergetic XML	XML file containing valid donation records only
Exceptions CSV	Excluded rows requiring correction
Audit CSV	Included rows with source and derived conversion values

---

Important Notes

• The app does not include the XML declaration header by default.
• The XML begins directly with the <Synergetic> root node.
• BankCode is omitted because the local Synergetic environment does not have a confirmed luBank lookup.
• Masked credit card numbers are omitted from XML because Synergetic describes the field as a full card number field.
• The app is configured for donation import and should not be used for debtor payments or GL-only receipts without further development.

---

Recommended User Workflow

1. Export donation payment data from Salesforce Payments2Us.
2. Upload the CSV into the Streamlit app.
3. Review Project Totals.
4. Review Exceptions.
5. Download and fix the exceptions CSV if any Synergetic IDs are missing.
6. Review the Audit tab.
7. Review the XML Preview tab.
8. Download the Synergetic XML.
9. Import the XML into Synergetic.
10. Retain the audit CSV for reconciliation and support.

---

Maintenance

Update the app configuration when:

• A new Salesforce merchant facility is introduced.
• A new Synergetic Fund or Appeal code is created.
• Credit card lookup codes change.
• Synergetic import requirements change.
• The Salesforce export structure changes.

Project mappings and lookup mappings should be reviewed before each major campaign or appeal launch.