Test Cases: Donations

⚠️ Gateway corrected — TraxionPay is fully removed. The donation feature is real on current code (POST /api/billing/donations, POST /api/billing/donations/invoice for online payment, GET /api/billing/admin/donations/report). Paynamics is the sole payment gateway — every "TraxionPay" reference below means Paynamics. Online donation payment creates an unpaid invoice and then routes through the standard Paynamics checkout; the authoritative sandbox channel codes and test-card values live in the Payments section (currently under active rewrite — do not trust the generic "Test Cards" table below). Manual-payment recording (Cash / Bank / Other) is admin-side and does not use the gateway.

Module: Billing & Invoicing - Donations

Priority: P1

Phase: 2

Backend Endpoints:

POST /api/billing/donations - Create donation
POST /api/billing/donations/invoice - Create donation invoice
GET /api/billing/admin/donations/report - Donations report (Admin)

Frontend Pages:

Member: Donation flow / checkout page
Admin: Admin donation report page

Prerequisites

User logged in with MEMBER role (for donation submission).
User logged in with ADMIN or FINANCE_MANAGER role (for donation reports).
Payment gateway (Paynamics) configured for online donations.
Manual payment methods enabled (Bank Transfer, GCash, Maya).
Email service operational for receipt emails.
Test data from 00_MASTER_TEST_DATA.md is seeded.

Test Data

Field	Value
Donor Member	Maria Cruz (MEM-2024-0004)
Donation Amount 1	PHP 5,000.00 (500000 cents)
Donation Amount 2	PHP 1,000.00 (100000 cents)
Donation Amount 3	PHP 10,000.00 (1000000 cents)
Currency	PHP
Admin User	Admin User (ADMIN)
Finance Manager	Ana Reyes (FINANCE_MANAGER)

Paynamics Sandbox Test Cards (placeholder — use the Payments section values)

Card Type	Number	Expiry	CVV	Result
Visa Success	4111 1111 1111 1111	12/25	123	Approved
Mastercard Success	5500 0000 0000 0004	12/25	123	Approved
Declined Card	4000 0000 0000 0002	12/25	123	Declined

Test Cases

TC-BIL-061: Create Donation - Member Flow (Happy Path)

Step	Action	Expected Result
1	Login as Maria Cruz (MEMBER).	Dashboard displayed.
2	Navigate to Donations page or "Make a Donation" link.	Donation form displayed.
3	Enter donation amount: PHP 5,000.00.	Amount field populated.
4	Verify currency is PHP (default).	Currency shows PHP.
5	Click "Continue" or "Donate".	API `POST /api/billing/donations` called.
6	Verify API response.	Status `201 Created`. Donation record created with amountCents: 500000, currency: PHP.
7	Verify donation ID generated.	Unique donation ID returned.
8	Verify redirect to payment options.	Payment method selection displayed.

TC-BIL-062: Create Donation - Validation Errors

Step	Action	Expected Result
1	Navigate to Donations page (logged in as MEMBER).	Donation form displayed.
2	Click "Donate" without entering amount.	Validation error: "Amount is required".
3	Enter amount: 0.	Validation error: "Amount must be greater than 0".
4	Enter negative amount: -500.	Validation error: "Amount must be greater than 0".
5	Enter invalid characters: "abc".	Validation error: "Invalid amount format".
6	Enter valid amount: PHP 1,000.00.	Amount accepted, able to proceed.

TC-BIL-063: Create Donation - Minimum Amount Validation

Step	Action	Expected Result
1	Navigate to Donations page.	Form displayed.
2	Enter very small amount: PHP 0.01 (1 cent).	Check if minimum donation threshold applies.
3	Verify system behavior.	Either accepted or "Minimum donation amount is PHP X" error.

TC-BIL-064: Create Donation Invoice

Step	Action	Expected Result
1	Login as Maria Cruz (MEMBER).	Dashboard displayed.
2	Create donation: PHP 5,000.00.	Donation created successfully.
3	System creates invoice for donation.	API `POST /api/billing/donations/invoice` called.
4	Verify invoice created.	Invoice generated with donation line item.
5	Verify invoice details.	Amount: PHP 5,000.00, Type: Donation, Status: PENDING.
6	Verify invoice number format.	Format: `RCME-DON-0001` (seeded donation invoices use the `RCME-DON-` prefix; dues use `RCME-DUES-`, events `RCME-EVT-`).
7	Verify member ID linked.	Invoice linked to Maria Cruz (MEM-2024-0004).

TC-BIL-065: Create Donation Invoice - Guest/Unauthenticated User

Step	Action	Expected Result
1	Access donation page without login (if allowed).	Check if guest donations supported.
2	Attempt `POST /api/billing/donations` without auth token.	Status `401 Unauthorized`.
3	Verify error message.	"Authentication required" or redirect to login.

Payment Flow Test Cases

TC-BIL-066: Donation Payment via Paynamics - Success

Step	Action	Expected Result
1	Login as Maria Cruz (MEMBER).	Dashboard displayed.
2	Create donation: PHP 5,000.00.	Donation and invoice created.
3	Select "Pay Online" payment option.	Paynamics gateway initiated.
4	Enter test card: 4111 1111 1111 1111.	Card number accepted (Visa).
5	Enter expiry: 12/25.	Expiry accepted.
6	Enter CVV: 123.	CVV accepted.
7	Click "Pay Now".	Payment processing initiated.
8	Wait for gateway response.	Success response received.
9	Verify redirect to success page.	"Donation Successful" or "Thank You" page displayed.
10	Verify invoice status updated.	Invoice status changed to PAID.
11	Verify donation status updated.	Donation marked as completed/paid.
12	Verify payment record created.	Payment record with gateway reference.

TC-BIL-067: Donation Payment via Paynamics - Declined Card

Step	Action	Expected Result
1	Create donation: PHP 5,000.00.	Donation created.
2	Select "Pay Online".	Gateway form displayed.
3	Enter declined card: 4000 0000 0000 0002.	Card entered.
4	Complete form and submit.	Processing initiated.
5	Verify response.	"Payment declined" error displayed.
6	Verify invoice unchanged.	Invoice remains PENDING.
7	Verify retry option available.	"Try Again" or alternative payment shown.

TC-BIL-068: Donation Payment via Paynamics - 3D Secure

Step	Action	Expected Result
1	Create donation and proceed to payment.	Gateway displayed.
2	Use 3DS-enrolled test card (if available).	Card entered.
3	Submit payment.	3DS challenge triggered.
4	Complete 3DS verification (OTP).	OTP entered and verified.
5	Return to merchant site.	Success page displayed.
6	Verify payment completed.	Invoice marked PAID, donation completed.

TC-BIL-069: Donation Payment via Bank Transfer (Manual)

Step	Action	Expected Result
1	Login as Maria Cruz (MEMBER).	Dashboard displayed.
2	Create donation: PHP 5,000.00.	Donation and invoice created.
3	Select "Bank Transfer" payment option.	Bank details displayed.
4	View bank account details.	Organization bank account info shown.
5	Upload proof of payment (screenshot/receipt).	File upload accepted (JPG, PNG, PDF).
6	Enter reference number from bank.	Reference field populated.
7	Submit payment proof.	API call to submit manual payment.
8	Verify submission confirmation.	"Payment submitted for verification" message.
9	Verify invoice status.	Invoice status: PENDING (awaiting admin approval).
10	Verify payment record created.	Payment record with status PENDING_VERIFICATION.

TC-BIL-070: Donation Payment via GCash (Manual)

Step	Action	Expected Result
1	Create donation: PHP 1,000.00.	Donation created.
2	Select "GCash" payment option.	GCash payment instructions displayed.
3	View GCash number/QR code.	Organization GCash details shown.
4	Upload payment screenshot.	Screenshot file uploaded.
5	Enter GCash reference number.	Reference entered.
6	Submit payment.	Payment submitted for verification.
7	Verify pending status.	Invoice: PENDING, Payment: PENDING_VERIFICATION.

TC-BIL-071: Donation Payment via Maya (Manual)

Step	Action	Expected Result
1	Create donation: PHP 2,500.00.	Donation created.
2	Select "Maya" payment option.	Maya payment instructions displayed.
3	View Maya account details.	Organization Maya details shown.
4	Upload payment proof.	Proof uploaded.
5	Enter Maya transaction reference.	Reference entered.
6	Submit payment.	Payment submitted for verification.
7	Verify pending status.	Awaiting admin approval.

TC-BIL-072: Manual Payment Approval (Admin)

Step	Action	Expected Result
1	Login as Ana Reyes (FINANCE_MANAGER).	Dashboard displayed.
2	Navigate to Admin > Payments (pending approvals).	List of pending payments displayed.
3	Locate Maria Cruz's donation payment.	Payment record visible.
4	View payment proof attachment.	Uploaded proof viewable.
5	Verify payment details match.	Amount, reference number checked.
6	Click "Approve Payment".	Approval confirmation dialog.
7	Confirm approval.	Payment approved.
8	Verify invoice status updated.	Invoice status: PAID.
9	Verify donation status updated.	Donation marked as completed.
10	Verify receipt email triggered.	Email queued for member.

TC-BIL-073: Manual Payment Rejection (Admin)

Step	Action	Expected Result
1	Login as FINANCE_MANAGER.	Dashboard displayed.
2	Navigate to pending payments.	Pending list displayed.
3	Locate a donation payment.	Payment found.
4	Click "Reject Payment".	Rejection dialog opens.
5	Enter rejection reason: "Invalid payment proof".	Reason entered.
6	Confirm rejection.	Payment rejected.
7	Verify invoice unchanged.	Invoice remains PENDING.
8	Verify notification sent to member.	Email/notification about rejection.

Admin Reports Test Cases

TC-BIL-074: Donations Report - Admin Access

Step	Action	Expected Result
1	Login as Admin User (ADMIN).	Dashboard displayed.
2	Navigate to Admin > Reports > Donations.	Donations report page displayed.
3	Verify API call.	`GET /api/billing/admin/donations/report` called.
4	Verify report columns displayed.	Date, Donor, Amount, Status, Payment Method visible.
5	Verify total donations summary.	Sum of all donations displayed.

TC-BIL-075: Donations Report - Finance Manager Access

Step	Action	Expected Result
1	Login as Ana Reyes (FINANCE_MANAGER).	Dashboard displayed.
2	Navigate to Donations Report.	Report accessible.
3	Verify full report functionality.	All features available (Manager role).

TC-BIL-076: Donations Report - Date Range Filter

Step	Action	Expected Result
1	Open Donations Report as ADMIN.	Report displayed.
2	Set date range: Start of current month to today.	Filter applied.
3	Verify filtered results.	Only donations within range displayed.
4	Verify totals recalculated.	Sum updated for filtered period.

TC-BIL-077: Donations Report - Status Filter

Step	Action	Expected Result
1	Open Donations Report.	Report displayed.
2	Filter by status: "Completed".	Only completed donations shown.
3	Filter by status: "Pending".	Only pending donations shown.
4	Clear filter to show all.	All donations displayed.

TC-BIL-078: Donations Report - Export to CSV

Step	Action	Expected Result
1	Open Donations Report with filters applied.	Filtered report displayed.
2	Click "Export CSV" or download button.	CSV download initiated.
3	Open downloaded CSV file.	File contains filtered donation data.
4	Verify CSV columns.	Date, Donor Name, Amount, Status, Payment Method, Reference.
5	Verify CSV totals row.	Total amount included (if applicable).

TC-BIL-079: Donations Report - Permission Denied (Member)

Step	Action	Expected Result
1	Login as Maria Cruz (MEMBER).	Member dashboard displayed.
2	Attempt to navigate to Admin > Donations Report.	Menu not visible or access denied.
3	Attempt direct API call `GET /api/billing/admin/donations/report`.	Status `403 Forbidden`.
4	Verify error message.	"Access denied" or "Insufficient permissions".

Donation Receipt Email Test Cases

TC-BIL-080: Donation Receipt Email - Sent on Payment Success

Step	Action	Expected Result
1	Complete donation payment (Paynamics or approved manual).	Payment successful.
2	Check MailHog for outgoing emails.	Email queued.
3	Verify recipient.	Email sent to testmember@rcme.membervu.com.
4	Verify subject line.	"Donation Receipt" or "Thank You for Your Donation".
5	Verify email body contains donation details.	Amount: PHP 5,000.00, Date, Reference/Invoice number.
6	Verify organization name in email.	Rotary Club of Manila Expats.
7	Verify PDF attachment (if applicable).	Donation receipt PDF attached.

TC-BIL-081: Donation Receipt Email - Content Verification

Step	Action	Expected Result
1	Open donation receipt email.	Email content displayed.
2	Verify donor name.	"Dear Maria Cruz" or member name.
3	Verify donation amount.	PHP 5,000.00 displayed correctly.
4	Verify donation date.	Date of donation shown.
5	Verify invoice/receipt number.	Reference number included.
6	Verify payment method.	"Credit Card" or "Bank Transfer" etc.
7	Verify organization contact info.	Contact details for questions.
8	Verify thank you message.	Appropriate acknowledgment text.

TC-BIL-082: Donation Receipt - No Email for Pending Payments

Step	Action	Expected Result
1	Submit manual donation payment (not yet approved).	Payment pending verification.
2	Check MailHog for receipt email.	No donation receipt sent.
3	Verify only confirmation email (if any).	"Payment submitted" notification, not receipt.
4	Admin approves payment.	Payment approved.
5	Verify receipt email now sent.	Receipt triggered after approval.

Donation History Test Cases

TC-BIL-083: Member View Own Donation History

Step	Action	Expected Result
1	Login as Maria Cruz (MEMBER).	Dashboard displayed.
2	Navigate to Donations History or My Donations.	Donation history page displayed.
3	Verify own donations listed.	All donations by Maria Cruz visible.
4	Verify columns displayed.	Date, Amount, Status, Receipt/Invoice link.
5	Verify default sorting.	Sorted by date (newest first).

TC-BIL-084: Member View Donation Details

Step	Action	Expected Result
1	View donation history list.	List displayed.
2	Click on a donation entry.	Donation detail view opens.
3	Verify donation details.	Amount, date, payment method, status displayed.
4	Verify linked invoice visible.	Invoice number with link to invoice detail.
5	Verify receipt download option.	"Download Receipt" button (for completed donations).

TC-BIL-085: Download Donation Receipt from History

Step	Action	Expected Result
1	Navigate to donation history.	History displayed.
2	Locate a completed donation.	Donation with PAID status.
3	Click "Download Receipt" or receipt icon.	PDF download initiated.
4	Verify PDF content.	Receipt contains donation details, organization info.
5	Verify PDF filename.	Format: donation-receipt-YYYY-XXXX.pdf or similar.

TC-BIL-086: Member Cannot View Other Members' Donations

Step	Action	Expected Result
1	Login as Maria Cruz (MEMBER).	Dashboard displayed.
2	View donation history.	Only Maria Cruz's donations shown.
3	Attempt to access another member's donation by URL manipulation.	Access denied or 404 Not Found.
4	Verify API endpoint restriction.	Donations filtered by authenticated memberId.

TC-BIL-087: Donation History - Empty State

Step	Action	Expected Result
1	Login as member with no previous donations.	Dashboard displayed.
2	Navigate to Donation History.	Empty state displayed.
3	Verify empty message.	"No donations yet" or similar message.
4	Verify "Make a Donation" call-to-action.	Link/button to start donating.

TC-BIL-088: Donation History - Pagination

Step	Action	Expected Result
1	Login as member with many donations (>10).	Dashboard displayed.
2	View donation history.	First page of donations displayed.
3	Verify pagination controls.	Page numbers or "Load More" visible.
4	Navigate to next page.	Additional donations loaded.
5	Verify consistent sorting.	Date order maintained across pages.

API Test Cases

TC-BIL-API-061: POST /api/billing/donations - Valid Request

Request:

{
  "amountCents": 500000,
  "currency": "PHP"
}

Headers: Authorization: Bearer

Expected Response: 201 Created

{ "id": "uuid", "memberId": "MEM-2024-0004", "amountCents": 500000, "currency": "PHP", "status": "PENDING", "createdAt": "timestamp"

}

TC-BIL-API-062: POST /api/billing/donations - Missing Amount

Request:

{
  "currency": "PHP"
}

Expected Response: 400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "amountCents is required"
}

TC-BIL-API-063: POST /api/billing/donations - Invalid Amount (Zero)

Request:

{
  "amountCents": 0,
  "currency": "PHP"
}

Expected Response: 400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "Amount must be greater than 0"
}

TC-BIL-API-064: POST /api/billing/donations - Invalid Amount (Negative)

Request:

{
  "amountCents": -100000,
  "currency": "PHP"
}

Expected Response: 400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "Amount must be greater than 0"
}

TC-BIL-API-065: POST /api/billing/donations - Unauthorized

Headers: No auth token or invalid token

Expected Response: 401 Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Authentication required"
}

TC-BIL-API-066: POST /api/billing/donations/invoice - Create Invoice for Donation

Request:

{
  "donationId": "donation-uuid"
}

Headers: Authorization: Bearer

Expected Response: 201 Created

{ "id": "uuid", "invoiceNumber": "RCME-DON-XXXX", "donationId": "donation-uuid", "memberId": "MEM-2024-0004", "amountCents": 500000, "status": "PENDING", "createdAt": "timestamp"

}

TC-BIL-API-067: GET /api/billing/admin/donations/report - Authorized (Manager)

Headers: Authorization: Bearer

Expected Response: 200 OK

{ "donations": [ { "id": "uuid", "memberName": "Maria Cruz", "amountCents": 500000, "currency": "PHP", "status": "PAID", "paymentMethod": "CARD", "createdAt": "timestamp" } ], "totalCount": 15, "totalAmountCents": 7500000, "currency": "PHP"

}

TC-BIL-API-068: GET /api/billing/admin/donations/report - Unauthorized (Member)

Headers: Authorization: Bearer

Expected Response: 403 Forbidden

{
  "error": "FORBIDDEN",
  "message": "Insufficient permissions"
}

TC-BIL-API-069: GET /api/billing/admin/donations/report - With Date Filter

Request: GET /api/billing/admin/donations/report?startDate=2024-01-01&endDate=2024-12-31

Headers: Authorization: Bearer

Expected Response: 200 OK

{
  "donations": [...],
  "totalCount": 10,
  "totalAmountCents": 5000000,
  "currency": "PHP",
  "dateRange": {
    "start": "2024-01-01",
    "end": "2024-12-31"
  }
}

Edge Cases

TC-BIL-090: Large Donation Amount

Step	Action	Expected Result
1	Create donation: PHP 1,000,000.00.	Large amount entered.
2	Verify system accepts amount.	No overflow or formatting issues.
3	Verify display formatting.	PHP 1,000,000.00 displayed correctly.
4	Verify payment gateway handles amount.	Gateway accepts large transaction.

TC-BIL-091: Multiple Concurrent Donations

Step	Action	Expected Result
1	Open two browser tabs as same member.	Both tabs logged in.
2	Initiate donation in both tabs simultaneously.	Both donations created.
3	Verify both donations tracked separately.	Unique IDs, separate invoices.
4	Verify no data corruption.	Amounts and details correct for each.

TC-BIL-092: Donation During System Maintenance

Step	Action	Expected Result
1	Simulate backend unavailable during payment.	Error occurs.
2	Verify graceful error handling.	User-friendly error message.
3	Verify no partial data.	No orphaned donation or invoice records.
4	Verify retry possible when system restored.	User can restart donation flow.

Summary

Category	Test Case Count
Create Donation (Member)	4
Create Donation Invoice	2
Payment via Paynamics	3
Payment via Manual Methods	5
Donations Report (Admin)	6
Donation Receipt Email	3
Donation History (Member)	6
API Test Cases	9
Edge Cases	3
Total	41