Payments Overview

The Batchmates payment system processes donations through PayMongo — the sole active payment gateway — covering hosted checkout flows, direct charges against vaulted cards, and gateway-managed recurring subscriptions.

Stack

Layer	Technology
Backend	Laravel 12
Frontend	React 19 + TypeScript
Database	PostgreSQL
Payment gateway	PayMongo

Payment Paths

Path	When used
Hosted Checkout	One-time donations (card, GCash, Maya wallet, GrabPay, QR Ph)
Charge saved card	One-time with a vaulted card
Recurring subscription	Automatic repeat billing against a vaulted card

Recurring donations are gateway-managed by PayMongo Subscriptions — PayMongo owns the billing schedule, invoicing, and retries; Batchmates only mirrors status via signed webhooks (subscription.invoice.paid, subscription.past_due, etc.). There is no local billing runner. See Fee Structure for how recurring invoices are fee-calculated.

Key Backend Services

File	Responsibility
`app/Services/PayMongoService.php`	Raw HTTP calls to PayMongo API
`app/Services/PayMongoTransactionService.php`	PayMongo business logic — initiate, charge, vault, webhook handling
`app/Services/FeeCalculator.php`	Gateway-agnostic fee computation

Checkout Flow (High Level)

User selects a campaign and donation amount on /donate
Frontend calls POST /api/v1/donations/quote to display the exact fee for the chosen method
Frontend posts to POST /api/v1/donations with payment_gateway: 'paymongo' and payment_method
Backend creates a pending Donation record and calls PayMongo's checkout API
Backend returns { redirectUrl } — frontend redirects the browser to the hosted payment page
User completes payment
PayMongo redirects back and fires a webhook
Webhook handler marks the donation completed and increments campaign balances

See Donation Flow for the full step-by-step sequence.

Saved Card Flow (High Level)

Frontend tokenizes the card directly against PayMongo's API (/payment_methods) using the public key — card data never touches Batchmates servers — producing a pm_... id
Frontend sends the pm_... id to POST /api/v1/payment-methods/paymongo/link-card
Backend creates a PayMongo customer (or reuses existing) and runs a ₱25 card verification charge with setup_future_usage to vault the card (PayMongo has no zero-amount setup intent)
User donates via POST /api/v1/donations/charge-saved/paymongo with the saved payment method ID and the card CVC (PayMongo requires CVC re-entry on every charge)
If 3DS is required, an action_url is returned — user authenticates, then the intent-return redirect finalises the donation

See PayMongo Saved Cards for the full vaulting flow.

API Endpoint Reference

Method	Path	Auth	Description
POST	`/api/v1/donations/quote`	Optional (public)	Server-authoritative fee preview — creates nothing
POST	`/api/v1/donations`	Sanctum	Create donation + initiate PayMongo checkout
POST	`/api/v1/donations/charge-saved/paymongo`	Sanctum	Charge a vaulted PayMongo card (requires CVC)
POST	`/api/v1/donations/{id}/pay/paymongo`	Sanctum	Retry a failed/expired PayMongo donation
POST	`/api/v1/payment-methods/paymongo/link-card`	Sanctum	Vault a PayMongo card (via `pm_...` id)
GET	`/api/v1/payment-methods`	Sanctum	List user's saved cards
DELETE	`/api/v1/payment-methods/{id}`	Sanctum	Remove a saved card
POST	`/api/v1/payment-methods/{id}/set-default`	Sanctum	Set default card
GET	`/api/v1/payments/paymongo/success`	Public	PayMongo post-checkout success redirect
GET	`/api/v1/payments/paymongo/cancel`	Public	PayMongo post-checkout cancel redirect — verifies with the gateway before cancelling
GET	`/api/v1/payments/paymongo/intent-return`	Public	PayMongo saved-card 3DS return
GET	`/api/v1/payments/paymongo/vault-return`	Public	PayMongo card-vaulting 3DS return
POST	`/api/v1/payments/paymongo/webhook`	Webhook sig	PayMongo event webhook