Fee Structure

How donation fees are calculated, what rates apply per payment method, and how the total charged amount is derived.

Source files: app/Services/FeeCalculator.php · config/fees.php · app/Http/Controllers/Api/DonationController.php

Two components, always kept separate

Every donation carries two distinct fee lines, stored separately on the Donation record and never summed into one "fee":

convenience_fee is a pass-through cost, not platform income — see Financial Reports for how reporting keeps this separate from actual revenue (system_fee).

Fee Rates — by gateway and method

Donors select a payment method in the UI before checkout, so the exact published rate for that method is charged — there is no more flat "hosted checkout" rate.

PayMongo — by method

Platform service fee

Environment Variables

# .env

APP_SERVICE_FEE_RATE=0.015

# PayMongo — per method (paymongo.com/pricing)
PAYMONGO_CARD_RATE=0.03125
PAYMONGO_CARD_FIXED=13.39
PAYMONGO_GCASH_RATE=0.0223
PAYMONGO_GCASH_FIXED=0.0
PAYMONGO_PAYMAYA_RATE=0.0179
PAYMONGO_PAYMAYA_FIXED=0.0
PAYMONGO_GRABPAY_RATE=0.0196
PAYMONGO_GRABPAY_FIXED=0.0
PAYMONGO_QRPH_RATE=0.0134
PAYMONGO_QRPH_FIXED=0.0
PAYMONGO_FALLBACK_RATE=0.03125
PAYMONGO_FALLBACK_FIXED=13.39

# Platform operating cost — reporting only, never charged to donors
PAYMONGO_PAYOUT_FEE=10.0

Usage

// app/Services/FeeCalculator.php

$fees = FeeCalculator::calculate('paymongo', 1000.00, 'gcash');
// [
//   'convenience_fee' => 22.30,   // 2.23% × 1000
//   'system_fee'      => 15.00,   // 1.5% × 1000
//   'total_amount'    => 1037.30,
// ]

Fee Quote Endpoint

{
  "amount": 1000,
  "payment_gateway": "paymongo",
  "payment_method": "gcash"
}

{
  "success": true,
  "data": {
    "amount": 1000,
    "convenience_fee": 22.30,
    "system_fee": 15.00,
    "total_amount": 1037.30,
    "breakdown": {
      "gateway_label": "GCash",
      "rate_percent": 2.23,
      "fixed_fee": 0,
      "service_fee_percent": 1.5
    }
  }
}

{
  "message": "The given data was invalid.",
  "errors": {
    "payment_method": ["The payment method field is required."]
  }
}

Worked Examples

PayMongo — ₱1,000 donation, GCash

PayMongo — ₱1,000 donation, Card

Recurring (Subscription) Donations

PayMongo subscriptions bill the fee-inclusive total, not just the base pledge — the PayMongo Plan is created for FeeCalculator::calculate('paymongo', $amount, 'card')['total_amount'] (subscriptions are always billed against a vaulted card, so the card tier applies). Each subscription.invoice.paid webhook re-derives the same convenience_fee/system_fee/total_amount split from the subscription's stored base amount, and credits the campaign by the base amount only — fees are platform revenue, same as one-time donations.

See app/Services/PayMongoSubscriptionService.php (createSubscription(), handleInvoicePaid()).

What Gets Sent to the Gateway

'amount' => (int) round($fees['total_amount'] * 100), // integer centavos

PayMongo hosted checkout also narrows payment_method_types to a single-element array containing the donor's chosen method — the amount quoted is guaranteed to be the only method PayMongo's page will actually offer:

'payment_method_types' => [$donation->payment_method], // e.g. ['gcash']

What Gets Credited to the Campaign

Campaign balances are incremented by the base donation amount only — fees are excluded, for both one-time and recurring donations:

$campaign->increment('raised_amount', $donation->amount);   // base amount
$campaign->increment('available_amount', $donation->amount); // base amount

Donation Record Fields