​
Overview

The Donation API tracks charitable contributions with multi-currency support and tax documentation. Donations can be recorded for various causes and recipients, with optional tax deduction tracking.

​
Endpoints

​
Record Donation

POST /api/donation Record a new charitable donation. Request Body: 
{
  "amount": 250.00,
  "currency": "USD",
  "cause": "Environmental Conservation",
  "recipient": "Green Earth Foundation",
  "taxDeductible": true,
  "receipt": "https://storage.example.com/receipt.pdf"
}
Supported Currencies:
  • USD, EUR, GBP, CAD, AUD
  • Automatic conversion to organization base currency

​
List Donations

GET /api/donation Retrieve donations with optional filtering. Query Parameters:
  • userId: Filter by specific user
  • limit: Max results (default: 100)

​
Get Statistics

GET /api/donation/stats Retrieve aggregated donation statistics. Response: 
{
  "data": {
    "totalAmount": 15750.00,
    "totalDonations": 89,
    "byCurrency": {
      "USD": 12500.00,
      "EUR": 2500.00,
      "GBP": 750.00
    },
    "averageDonation": 177.00,
    "topCauses": [
      {
        "cause": "Environmental Conservation",
        "amount": 5200.00,
        "count": 23
      },
      {
        "cause": "Education",
        "amount": 4800.00,
        "count": 31
      }
    ]
  }
}

​
Tax Documentation

​
Tax-Deductible Donations

{
  "taxDeductible": true,
  "receipt": "https://storage.example.com/receipt.pdf"
}
Requirements:
  • Official receipt from charity required
  • Amount and date must be verifiable
  • Charity must be 501(c)(3) equivalent in local jurisdiction

​
Receipt Storage

Receipts are stored securely and linked to donation records:
  • PDF format preferred
  • Automatic OCR for amount verification
  • Secure cloud storage with access controls

​
Multi-Currency Support

​
Currency Conversion

{
  "amount": 100.00,
  "currency": "EUR",
  "convertedAmount": 108.50,
  "convertedCurrency": "USD",
  "exchangeRate": 1.085
}
  • Real-time exchange rates
  • Historical rate locking
  • Organization base currency configuration

​
Business Rules

  • Receipt Required: Tax-deductible donations must include receipt
  • Amount Validation: Minimum donation $1.00 (or equivalent)
  • Charity Verification: Recipients validated against charity databases
  • Audit Trail: All donations logged with immutable records
  • Privacy: Donor information protected under privacy regulations

​
Integration Examples

​
Corporate Matching

{
  "amount": 500.00,
  "cause": "Employee Matching Program",
  "recipient": "United Way",
  "matched": true,
  "matchAmount": 500.00,
  "matchSource": "Corporate Match Program"
}

​
Volunteer Mileage

{
  "amount": 45.00,
  "cause": "Volunteer Mileage Reimbursement",
  "recipient": "Local Food Bank",
  "taxDeductible": true,
  "category": "volunteer_support"
}

​
Response Examples

Successful Donation: 
{
  "data": {
    "id": "donation-uuid",
    "amount": 250.00,
    "currency": "USD",
    "cause": "Environmental Conservation",
    "recipient": "Green Earth Foundation",
    "userId": "user-uuid",
    "organizationId": "org-uuid",
    "taxDeductible": true,
    "receipt": "https://storage.example.com/receipt.pdf",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
Statistics Response: 
{
  "data": {
    "totalAmount": 45250.00,
    "totalDonations": 156,
    "byCurrency": {
      "USD": 38750.00,
      "EUR": 4500.00,
      "GBP": 2000.00
    },
    "averageDonation": 290.06,
    "topCauses": [
      {
        "cause": "Environmental Conservation",
        "amount": 15200.00,
        "count": 45
      }
    ]
  }
}