Donations API

Process donations, track payment status, and generate receipts.

Create Donation

POST /api/v1/donations

Create a new donation to a fundraiser. Can be made as a guest or authenticated user.

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(`${API_BASE}/donations`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fundraiser_id: '123e4567-e89b-12d3-a456-426614174000',
    amount: 10000,  // $100.00 in cents
    currency: 'USD',
    donor_name: 'Jane Smith',
    donor_email: 'jane@example.com',
    is_anonymous: false,
    message: 'Great cause! Keep up the excellent work.',
    payment_method_id: 'pm_card_visa'  // Stripe payment method
  })
});

const donation = await response.json();
console.log('Donation created:', donation.id);
console.log('Receipt sent to:', donation.donor_email);

Get Donation

GET /api/v1/donations/:id 🔒 Requires Authentication

Retrieve donation details. Only the donor or fundraiser owner can view.

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const donationId = '456e7890-e89b-12d3-a456-426614174000';

const response = await fetch(`${API_BASE}/donations/${donationId}`, {
  credentials: 'include'
});

const donation = await response.json();

console.log('Amount:', donation.amount / 100);
console.log('Status:', donation.status);
console.log('Fee:', donation.fee_amount / 100);

List My Donations

GET /api/v1/donations/me 🔒 Requires Authentication

Retrieve all donations made by the authenticated user.

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(`${API_BASE}/donations/me?limit=20&offset=0`, {
  credentials: 'include'
});

const donations = await response.json();

donations.forEach(d => {
  console.log(`$${d.amount/100} to ${d.fundraiser.title}`);
});

Get Fundraiser Donations

GET /api/v1/fundraisers/:id/donations

Retrieve all donations for a specific fundraiser (public donations only).

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const fundraiserId = '123e4567-e89b-12d3-a456-426614174000';

const response = await fetch(
  `${API_BASE}/fundraisers/${fundraiserId}/donations?limit=10`
);

const donations = await response.json();

// Only shows non-anonymous donations
donations.forEach(d => {
  console.log(`${d.donor_name}: $${d.amount/100}`);
});

Download Receipt

GET /api/v1/donations/:id/receipt 🔒 Requires Authentication

Download a PDF receipt for a donation.

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const donationId = '456e7890-e89b-12d3-a456-426614174000';

const response = await fetch(
  `${API_BASE}/donations/${donationId}/receipt`,
  {
    credentials: 'include'
  }
);

const blob = await response.blob();
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = `receipt-${donationId}.pdf`;
a.click();

Refund Donation

POST /api/v1/donations/:id/refund 🔒 Requires Authentication

Request a refund for a donation (admin or fundraiser owner only).

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const donationId = '456e7890-e89b-12d3-a456-426614174000';

const response = await fetch(
  `${API_BASE}/donations/${donationId}/refund`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      reason: 'Requested by donor',
      amount: 10000  // Optional: partial refund in cents
    })
  }
);

if (response.ok) {
  console.log('Refund processed successfully');
}

Response Codes

• 200 - Success
• 201 - Donation created successfully
• 400 - Bad request / Validation errors
• 401 - Authentication required
• 403 - Permission denied
• 404 - Donation not found
• 429 - Rate limit exceeded
• 500 - Server error