Payments Overview
The Batchmates payment system processes donations through Magpie, supporting GCash, Maya, and card payments via a hosted checkout flow, as well as direct charges against vaulted cards.
| Layer | Technology |
|---|
| Backend | Laravel 12 |
| Frontend | React 19 + TypeScript |
| Database | PostgreSQL |
| Payment gateway | Magpie |
| Path | When used | Mechanism |
|---|
| Magpie Checkout | One-time donations (GCash, Maya, card) | Redirect to Magpie-hosted page |
| Charge saved card | One-time or recurring with a vaulted card | Direct API charge via customer + source |
| File | Responsibility |
|---|
app/Services/MagpieService.php | Raw HTTP calls to Magpie API |
app/Services/MagpieTransactionService.php | Business logic — initiate, charge, webhook handling |
app/Services/FeeCalculator.php | Fee computation |
- User selects a campaign and donation amount on
/donate
- Frontend posts to
POST /api/v1/donations with payment_gateway: 'magpie'
- Backend creates a
pending Donation record and calls Magpie Checkout API
- Backend returns
{ redirectUrl } — frontend redirects the browser to Magpie's hosted page
- User completes payment (GCash / Maya / card)
- Magpie 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.
- User adds a card via a two-step flow: frontend tokenizes via
POST /api/v1/payments/magpie/create-source, then saves the resulting source ID via POST /api/v1/payment-methods
- User initiates a donation via
POST /api/v1/donations/charge-saved with the saved payment method ID
- Backend charges the vaulted card directly — no redirect needed
- Webhook
charge.succeeded marks the donation complete
See Saved Cards for full vaulting and charging details.
| Method | Path | Auth | Description |
|---|
| POST | /api/v1/donations | Sanctum | Create donation + initiate Magpie checkout |
| POST | /api/v1/donations/charge-saved | Sanctum | Charge a vaulted card directly |
| POST | /api/v1/payments/magpie/create-source | Sanctum | Tokenize a card with Magpie (step 1 of card vaulting) |
| POST | /api/v1/payment-methods | Sanctum | Vault a tokenized card source (step 2 of card vaulting) |
| 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/magpie/success | Public | Post-checkout success redirect |
| GET | /api/v1/payments/magpie/cancel | Public | Post-checkout cancel redirect |
| POST | /api/v1/payments/magpie/webhook | Webhook sig | Magpie event webhook |