feat(payment): integrate online payment gateway

[devstygian]

Summary

Implement an online payment gateway to enable secure cashless transactions within the POS system. This feature will provide customers with multiple payment options while ensuring that all payment records are accurately stored and linked to their respective orders.

The implementation should prioritize providers that offer free development environments or sandbox testing suitable for academic and capstone projects.

---

Objectives

• Integrate a secure payment gateway.
• Support digital payment methods.
• Record payment transactions in the database.
• Update order status after successful payment.
• Generate transaction receipts containing payment information.
• Handle payment failures and cancellations gracefully.

---

Recommended Payment Providers

1. PayMongo (Recommended)

Status: Preferred

Features

• GCash
• Maya
• GrabPay
• QR Ph
• Credit/Debit Cards
• Hosted Checkout
• Sandbox Environment
• REST API

Advantages

• Free testing environment
• Well-documented API
• Suitable for PHP applications
• Supports multiple Philippine payment channels

Documentation:
https://developers.paymongo.com/

---

2. Xendit

Features

• GCash
• Maya
• QR Ph
• Credit/Debit Cards
• Virtual Accounts
• Sandbox Environment

Documentation:
https://developers.xendit.co/

---

3. PayPal

Features

• Credit/Debit Cards
• PayPal Wallet
• Sandbox Environment

Documentation:
https://developer.paypal.com/

---

4. Stripe

Features

• Credit/Debit Cards
• Apple Pay
• Google Pay
• Test Mode

Documentation:
https://stripe.com/docs

---

5. Local Payment Simulation (Fallback)

If third-party payment providers are unavailable, implement a simulated payment workflow for demonstration purposes.

Example Flow

Order Created
↓
Select Payment Method
↓
Generate Reference Number
↓
Payment Successful
↓
Update Order Status
↓
Generate Receipt

---

Functional Requirements

• Add "Online Payment" as a payment option.
• Allow selection of supported payment providers.
• Create payment sessions using the selected provider.
• Store transaction reference numbers.
• Save payment provider information.
• Update payment status automatically.
• Generate receipts after successful payment.
• Display appropriate error messages for failed transactions.

---

Database Changes

orders

Add the following fields:

• payment_method
• payment_provider
• payment_reference
• payment_status
• paid_at

---

Payment Status

• Pending
• Paid
• Failed
• Cancelled
• Refunded

---

Acceptance Criteria

• Customers can choose an online payment method.
• Payment transactions are successfully recorded.
• Order status updates automatically after payment.
• Receipts include payment details.
• Failed or cancelled payments are handled correctly.
• Sandbox mode functions successfully during testing.

---

Priority

High

Labels

enhancement
feature
payment
api
backend