> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout

> Mapping between WeGive Payouts and Salesforce custom Payout objects

**Salesforce Object:** `wegive__Payout__c` (custom object)<br />**WeGive Model:** Payout

## Overview

This document describes how payout data syncs from WeGive to Salesforce. Payouts represent the transfer of funds from a payment processor to the organization's bank account. Each payout carries a financial summary showing donation income, fees, refunds, disputes, reserve movements, and deposit amounts.

<Note>
  This feature requires the WeGive managed package to be installed in Salesforce, which includes the custom `wegive__Payout__c` object. A few payout fields were added in package version 0.7; on older package versions those fields are automatically omitted from the payload.
</Note>

***

## How Payout Data Syncs

### Direction

* **Export to Salesforce** only. Payouts originate with the payment processor and WeGive is the system of record; there is no import of payouts from Salesforce.

### Mapping Types

* **Hard-coded** - Sent by default on every push
* **Configurable (mapping rule)** - Available to payout mapping rules; sent only when a rule targets a Salesforce field

***

## Sync Configuration

* **Push payouts** - Enables the export of WeGive payouts to Salesforce

***

## Sync Triggers

Payout data is exported from WeGive to Salesforce when:

* **Payout Created:** A new payout is received from the payment processor
* **Payout Updated:** An existing payout is modified (e.g., reconciled, deposits recorded)

The export happens automatically after the create or update action in WeGive.

***

## Sync Process Overview

When a Payout is pushed, the integration:

1. **Generates the financial summary** from all transactions in the payout: total donations (gross and fee), service revenue (gross and fee), donation and service revenue refunds, disputes and chargebacks, other fees, and balance released/reserved.
2. **Compiles deposit information:** up to two deposit amounts.
3. **Creates or updates the record:** if the payout has a `salesforce_id` it **UPDATES** the existing record; otherwise it **CREATES** one (a lock prevents concurrent pushes from creating duplicates).
4. **Applies mapping rules:** any export-level mapping rules with `integration` = 'payout' are merged into the default payload.

***

## Default Field Mapping

These fields are sent on every push.

| Salesforce Field | WeGive Field | WeGive API Field | Direction | Type | Notes |
| :- | :- | :- | :- | :- | :- |
| Id | Salesforce ID | salesforce\_id | Import from Salesforce | Hard-coded | Stored on the WeGive payout after the first push |
| wegive\_\_Payout\_Id\_\_c | WeGive Payout ID | id | Export to Salesforce | Hard-coded | WeGive's unique identifier |
| wegive\_\_Payout\_Date\_\_c | Payout Date | paid\_at | Export to Salesforce | Hard-coded | Date funds were paid out |
| wegive\_\_Processor\_\_c | Processor Label | processor\_label | Export to Salesforce | Hard-coded | `[processor] - [payout_id] - [reference]` |
| wegive\_\_Number\_of\_Transactions\_\_c | Transaction Count | transactions\_count | Export to Salesforce | Hard-coded | Count of all transactions in the payout |
| wegive\_\_Balance\_Released\_\_c | Balance Released | summary.balance\_released | Export to Salesforce | Hard-coded | Funds released from reserve |
| wegive\_\_Balance\_Reserved\_\_c | Balance Reserved | summary.balance\_reserved | Export to Salesforce | Hard-coded | Stored as a negative value |
| wegive\_\_Disputed\_\_c | Has Disputes | (derived) | Export to Salesforce | Hard-coded | **Checkbox**: true when the disputed amount is nonzero |
| wegive\_\_Total\_Other\_Fees\_\_c | Other Fees | summary.total\_other\_fees | Export to Salesforce | Hard-coded | Miscellaneous fee line items |
| wegive\_\_Total\_Donation\_Income\_\_c | Total Donation Income | summary.total\_donation\_income | Export to Salesforce | Hard-coded | Gross tax-deductible donations |
| wegive\_\_Total\_Donation\_Fees\_\_c | Total Donation Fees | summary.total\_donation\_fees | Export to Salesforce | Hard-coded | Fees on donations |
| wegive\_\_Total\_Donation\_Income\_Refunds\_\_c | Donation Refunds | summary.total\_donation\_income\_refunds | Export to Salesforce | Hard-coded | Refunded donations |
| wegive\_\_Total\_Service\_Revenue\_Income\_\_c | Service Revenue Income | summary.total\_service\_revenue\_income | Export to Salesforce | Hard-coded | Gross non-deductible revenue; package 0.7+ |
| wegive\_\_Service\_Revenue\_Fees\_\_c | Service Revenue Fees | summary.service\_revenue\_fees | Export to Salesforce | Hard-coded | Fees on service revenue |
| wegive\_\_Total\_Service\_Revenue\_Income\_Refunds\_\_c | Service Revenue Refunds | summary.total\_service\_revenue\_income\_refunds | Export to Salesforce | Hard-coded | Refunded service revenue |
| wegive\_\_Deposit\_1\_Amount\_\_c | First Deposit Amount | deposit\_1\_amount | Export to Salesforce | Hard-coded | Package 0.7+; see Multiple Deposits |
| wegive\_\_Deposit\_2\_Amount\_\_c | Second Deposit Amount | deposit\_2\_amount | Export to Salesforce | Hard-coded | Package 0.7+; see Multiple Deposits |
| wegive\_\_Last\_Sync\_Date\_\_c | Last Sync | (generated) | Export to Salesforce | Hard-coded | Timestamp of the push |

### Additional Fields Available to Mapping Rules

The following values are exposed to payout mapping rules but are not sent by default:

| WeGive API Field | Description |
| :- | :- |
| summary.disputed\_amount | Dollar total of disputes and chargebacks. Map to `wegive__Disputed_Amount__c` on package versions that include it. |
| summary.gross\_total | Gross total of all line items, matching the payout page's Gross Total |
| summary.total\_fees | Total fees (negative), matching the payout page's Fee Total |
| summary.net\_payout | Net payout, matching the payout page's Net Payout |
| (any payout attribute) | Raw payout columns such as `amount`, `reference`, `payment_processor`, `status` |

Any default field can also be overridden or supplemented with a mapping rule.

***

## Important Notes

### Amount Conversion

WeGive stores amounts in cents; every amount in the payload is divided by 100 before it is sent.

### Disputed Checkbox vs. Disputed Amount

`wegive__Disputed__c` is a Checkbox in the managed package, so the default payload sends `true`/`false`. Sending a dollar amount to it would be rejected by Salesforce. To record the amount, add a mapping rule from `summary.disputed_amount` to a currency field such as `wegive__Disputed_Amount__c`.

### Multiple Deposits

* **No deposit records:** `Deposit_1_Amount__c` = the total payout amount
* **One deposit:** `Deposit_1_Amount__c` = that deposit's amount
* **Two deposits:** both fields populated
* **Three or more deposits:** **neither** deposit field is sent; use the payout total and WeGive's payout detail for reconciliation

### Reserved Balance (Negative Values)

`Balance_Reserved__c` is sent as `abs(amount) * -1` so it reads as a deduction in reports.

### Processor Label

`wegive__Processor__c` combines the processor name, WeGive payout ID, and processor reference: `Stripe - 12345 - po_abc123`.

### Package Version Handling

`wegive__Total_Service_Revenue_Income__c`, `wegive__Deposit_1_Amount__c`, `wegive__Deposit_2_Amount__c`, and `wegive__Last_Sync_Date__c` are stripped from the payload when the target org's package does not yet include them, so pushes do not fail on older installs.

### Legacy Custom Implementation

One legacy organization uses a differently named custom payout object with un-namespaced field names (for example `Payout_Date__c` instead of `wegive__Payout_Date__c`). On that implementation, `Disputed__c` carries the dollar amount, the processor field holds only the processor name, mapping rules are not applied, and `Last_Sync_Date` is not sent. This is not configurable; new implementations use `wegive__Payout__c`.

***

## Payout Matching & Create/Update Logic

* If the WeGive payout has a `salesforce_id`: **UPDATE** the existing Payout record
* If not: **CREATE** a new Payout record and store its ID on the WeGive payout

Payouts are matched only by Salesforce ID; there is no matching by date or amount.

***

## Required Fields

The default payload always includes `wegive__Payout_Id__c`, `wegive__Payout_Date__c`, `wegive__Processor__c`, and `wegive__Number_of_Transactions__c`. Salesforce does not require any specific payout field beyond what your org's validation rules enforce.

***

## Troubleshooting

**Payout not syncing:**

* Verify the WeGive managed package is installed and the Push payouts toggle is enabled
* Check that the payout was created or modified in WeGive

**Deposit fields blank:**

* Payouts with three or more deposits do not populate either deposit field
* On package versions before 0.7 the deposit fields are omitted

**Disputed field shows a checkbox, not an amount:**

* This is expected; map `summary.disputed_amount` to a currency field via a mapping rule

**Amounts don't match bank statement:**

* Sum both deposit amounts for split payouts
* Account for balance released/reserved, fees, refunds, and disputes; the optional `summary.gross_total`, `summary.total_fees`, and `summary.net_payout` fields reproduce the totals on the WeGive payout page

***

## Related Documentation

* [Opportunity & Payment](./opportunity)

*Verified against the integration source, September 2026.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.