Parsing Single and Multi Designation Donation Created Webhook Payloads
Understanding how donations are split across funds in Donation Created webhooks.
When processing Donation Created (transaction_set.created) webhooks, a donation can be allocated to a single designation or split across multiple designations. Correctly identifying the donation type is critical. Misinterpreting the transaction structure can lead to incorrect fund attribution, duplicated totals, or misreported fees.
Single Designation Donations
A single designation donation contains exactly one transaction object. That transaction represents the entire donation, including payment, fees, and fund allocation.
Key Characteristics
- Transactions Array: Always contains one object (i.e. transactions.length = 1)
- net_proceeds: Always matches client_proceeds for single designation donations.
- Payment Fields: Always populated on this transaction.
- Designation Object: Fully populated and represents the sole fund receiving the donation.
- client_proceeds: The amount allocated to the organization.
- net_proceeds: Always matches client_proceeds for single designation donations.
- donor_paid_fee: The processing fee paid by the donor, if applicable.
Partial Payload Example
{
"transactions": [
{
"id": "b0e9b111-7fde-4adf-ac13-813804756b53",
"description": "Cash Donation: $10.60",
"designation": {
"id": "11139903-ba9c-47ed-a152-545ffd539654",
"code": "test code",
"title": "Test Title"
},
"client_proceeds": 10.6,
"donor_paid_fee": 0.6,
"card_type": "visa",
"last_four_digits": "1111",
"payment_gateway_id": "00000000-a148-4573-887b-6a0bfcc7bf84",
}
]
}
For a full payload example refer to Donation Created Payload > Single Designation on {add page link}.
Multi-Designation Donations
A multi designation donation splits one payment across multiple funds, resulting in multiple transaction objects. The first transaction (parent) contains payment details, while subsequent transactions (children) contain individual fund allocations.
In a multi designation donation, there is still a single payment event. The donation is represented as multiple transaction records for accounting and allocation purposes only, not multiple charges.
Key Characteristics
Parent Transaction (Index 0)
- Payment Fields: Always populated on this transaction.
- Designation Object: Fields are always null.
- Description Format: "Cash Multi-Donation [0/N]: $fee/$total".
- client_proceeds: Processing fee amount when donor covers fees, otherwise 0.0.
- net_proceeds: Total donation amount across all designations.
- donor_paid_fee: The transaction fee amount.
- Embed Object: Always populated on the parent transaction.
- frequency and recurring_count: Appear only on the parent transaction for recurring donations.
- schedule_id: Present and shared across all transactions for recurring donations.
Child Transactions (Index 1-N)
- Payment Fields: Always null on this transaction.
- Designation Object: Fields are populated with applicable designation metadata.
- Description Format: "Cash Multi-Donation [X/N]: $amount".
- client_proceeds: The amount allocated to the specific designation.
- net_proceeds: Always 0.0 for child transactions and should not be used for totals.
- donor_paid_fee: Always null.
- Embed Object: Always niull on child transactions.
- frequency and recurring_count: Always null.
- schedule_id: Present and shared across all transactions for recurring donations.
Important: Do not calculate donation totals by summing net_proceeds across transactions. Always use the parent transaction’s net_proceeds.
Partial Payload Example
{
"transactions": [
{
// Parent Transaction [0]
"id": "111a9a27-5927-4233-942f-72c9ae139f9b",
"description": "Cash Multi-Donation [0/3]: $2.85/$102.85",
"designation": {
"id": null,
"code": null,
"title": null
},
"client_proceeds": 2.85,
"net_proceeds": 102.85,
"donor_paid_fee": 2.85,
"card_type": "visa",
"last_four_digits": "1111",
"payment_gateway_id": "111a6fbc-a148-4573-887b-6a0bfcc7bf84"
},
{
// Child Transaction [1]
"id": "1d3b2111-ab21-4626-9954-bb1e896475bf",
"description": "Cash Multi-Donation [1/3]: $50.00",
"designation": {
"id": "04039111-ba9c-47ed-a152-545ffd539654",
"code": "general_fund",
"title": "General Fund"
},
"client_proceeds": 50.0,
"card_type": null,
"payment_gateway_id": null
},
{
// Child Transaction [2]
"id": "5a9a111-636d-493b-9549-0332e8705050",
"description": "Cash Multi-Donation [2/3]: $25.00",
"designation": {
"id": "e1f750c4-1111-45b5-817a-5ad0d156ea7e",
"code": "greatest_need",
"title": "Greatest Need"
},
"client_proceeds": 25.0,
"card_type": null,
"payment_gateway_id": null
},
{
// Child Transaction [3]
"id": "c0f17e77-88e2-4648-8fa4-83e36c722000",
"description": "Cash Multi-Donation [3/3]: $25.00",
"designation": {
"id": "b0911e54-b150-4ad1-9176-bcae53548000",
"code": "food_bank",
"title": "Food Bank"
},
"client_proceeds": 25.0,
"card_type": null,
"payment_gateway_id": null
}
]
}