Donation Flow

1. User selects campaign + amount

The donation UI lives at /donate (React, Donate.tsx). It is a 5-step flow:

1. Browse campaigns
2. Enter amount
3. Choose payment method
4. Confirm details
5. Redirect to gateway

/donate/:id skips directly to the amount step for a specific campaign.

2. Frontend fetches a fee quote, then posts to the API

The frontend never computes fees itself — it calls POST /donations/quote with the chosen amount/method and displays the response verbatim before the donor confirms. See Fee Structure for the quote endpoint's request/response shape.

// Frontend — Donate.tsx
const res = await api.post('/donations', {
  campaign_id: 1,
  amount: 1000,
  payment_gateway: 'paymongo',
  payment_method: 'gcash',
  message: 'Keep up the good work!',
})
const redirectUrl: string = res.data.data.redirectUrl

// Validate destination before redirecting — prevents open redirect exploitation
const allowedHosts = ['paymongo.com', 'checkout.paymongo.com', 'pm.link']
const parsed = new URL(redirectUrl)
if (!allowedHosts.some(h => parsed.hostname === h || parsed.hostname.endsWith('.' + h))) {
  throw new Error('Unexpected payment redirect destination.')
}
window.location.href = redirectUrl

3. Backend creates a pending Donation

A Donation record is saved to the database with status: 'pending' before the gateway is called. This ensures the record exists even if the redirect fails.

4. PayMongo checkout session is created

// app/Services/PayMongoTransactionService.php
private function executeCheckout(Donation $donation): array
{
    $fees = FeeCalculator::calculate('paymongo', $donation->amount, $donation->payment_method);

    $session = $this->paymongo->createCheckoutSession([
        'line_items' => [[
            'currency' => 'PHP',
            'amount'   => (int) round($donation->total_amount * 100), // centavos
            'name'     => 'Donation — '.($campaign->title ?? 'Campaign'),
            'quantity' => 1,
        ]],
        'payment_method_types' => [$donation->payment_method],
        'success_url' => config('app.url').'/api/v1/payments/paymongo/success?id='.urlencode($donation->reference_number),
        'cancel_url'  => config('app.url').'/api/v1/payments/paymongo/cancel?id='.urlencode($donation->reference_number),
        'reference_number' => $donation->reference_number,
    ]);

    $donation->update(['transaction_id' => $session['id']]);

    return ['redirectUrl' => $session['attributes']['checkout_url']];
}

The response contains a hosted checkout URL. The backend returns it as redirectUrl.

5. User pays on PayMongo's hosted page

Supported methods: GCash, Maya wallet, card, GrabPay, QR Ph — narrowed to the single method the donor chose in step 2.

6. PayMongo redirects back

The ?id= parameter is the donation's reference_number. Both handlers call verifyAndComplete() to confirm payment status with PayMongo's API before writing anything — PayMongo's post-payment screen has a back link pointing at cancel_url, so a paid checkout can arrive on the cancel redirect. The cancel handler only marks the donation cancelled if the gateway confirms no payment and the status is still pending; if the gateway confirms payment, the donation completes and the donor is redirected to the success page instead. A completed or failed donation is never cancelled via this redirect.

The frontend /donations/success page reads the ?id= query param (the reference_number UUID) to display the right donation.

7. PayMongo fires a webhook

Regardless of the redirect, PayMongo sends a server-to-server POST to /api/v1/payments/paymongo/webhook, signed with the Paymongo-Signature header. This is the authoritative signal — never trust the redirect alone.

See Webhooks for endpoint security and event handling.

8. Donation status is updated

// app/Services/PayMongoTransactionService.php
private function completeDonation(Donation $donation): void
{
    $donation->update(['status' => 'completed', 'paid_at' => now()]);

    $donation->campaign->increment('raised_amount', $donation->amount);
    $donation->campaign->increment('available_amount', $donation->amount);
    $donation->campaign->increment('supporter_count');
}

Campaign balances are incremented by the base donation amount, not the total_amount (which includes fees).