Payments API

Base path: /api/payments
File: ayts-api/src/routes/payments.ts
Auth required: Yes
Provider: PayMongo

POST /api/payments/initiate

Initiate payment for an order.

Request:

{
  "orderId": "uuid",
  "paymentMethod": "cash_on_delivery" | "gcash" | "maya" | "dragonpay"
}

Response (COD):

{
  "success": true,
  "orderId": "uuid",
  "paymentMethod": "cash_on_delivery",
  "status": "confirmed"
}

Response (GCash / Maya):

{
  "success": true,
  "orderId": "uuid",
  "paymentMethod": "gcash",
  "checkoutUrl": "https://pay.paymongo.com/source/...",
  "sourceId": "src_..."
}

After getting checkoutUrl, redirect the customer:

window.location.href = result.checkoutUrl;

---

GET /api/payments/:orderId

Get payment status for an order.

Response 200:

{
  "success": true,
  "payment": {
    "orderId": "uuid",
    "status": "paid" | "pending" | "failed",
    "method": "gcash",
    "amount": 720.00,
    "paymongoReference": "pay_..."
  }
}

---

PATCH /api/payments/refund/:orderId/process

Process a refund for an order. Requires admin role.

{
  "amount": 720.00,
  "reason": "Customer requested cancellation"
}

Response 200:

{
  "success": true,
  "refundId": "ref_...",
  "amount": 720.00,
  "status": "pending"
}

---

POST /api/webhooks/paymongo

PayMongo webhook handler. Called by PayMongo when payment status changes.

Headers required:

paymongo-signature: {hmac-sha256-signature}

Events handled:

Event	Action
source.chargeable	Charge the source (GCash/Maya)
payment.paid	Mark order as confirmed
payment.failed	Mark payment as failed

Security: Webhook signature verified with HMAC-SHA256 using PAYMONGO_WEBHOOK_SECRET.

---

PayMongo Setup

1. Create account at paymongo.com
2. Get API keys from PayMongo dashboard
3. Set webhook URL: https://ayts-api.jerquinbayudo.workers.dev/api/webhooks/paymongo
4. Set secrets via wrangler:

wrangler secret put PAYMONGO_SECRET_KEY --env production
wrangler secret put PAYMONGO_WEBHOOK_SECRET --env production

---

Commission

3% of each order's total is platform commission. This is tracked in the payments table and visible in admin analytics.