⚡ Quick Start • 🔗 Integration Guide • 🛡 Security Checklist • 🩹 Troubleshooting

✨ Overview

ProStore is a modular, production-ready Next.js template designed to get Cambodian developers from git clone to a working ABA PayWay checkout in minutes — not days.

It comes pre-configured with sandbox and production environments, fully typed payment utilities, and secure webhook-ready API routes.

🔐 Payments	🛠 Developer Experience
• Sandbox & production environments • Webhook-ready API routes • Modular, reusable payment utilities	• Full TypeScript support • ESLint + Prettier preconfigured • Clear, documented project structure

🧱 Tech Stack

Layer	Technology
Framework	Next.js 14 (Pages Router)
Language	TypeScript / JavaScript
Styling	Tailwind CSS + CSS Modules
Payments	ABA PayWay API (Sandbox & Production)
Tooling	ESLint · Prettier · TypeScript

🚀 Quick Start

Prerequisites: Ensure you have Node.js (v18+) and npm installed.

# 1. Clone the repository
git clone https://github.com/SereyodamChek/ProStore_PayWay-Intergration.git
cd ProStore_PayWay-Intergration

# 2. Install dependencies
npm install

# 3. Configure environment variables
cp .env.example .env
# → Edit .env with your PayWay credentials

# 4. Start the development server
npm run dev

Then open http://localhost:3000 and you're live! 🎉

Command	Description
npm run dev	Start the development server
npm run build	Build the application for production
npm run start	Start the production server
npm run lint	Run ESLint + TypeScript checks
npm run type-check	Verify TypeScript compilation

🔑 Environment Variables

Copy .env.example to .env and populate the required values.

# ─── ABA PayWay Configuration ───
PAYWAY_API_URL=https://checkout-sandbox.payway.com.kh/api/v1
# Production URL: https://checkout.payway.com.kh/api/v1

PAYWAY_MERCHANT_ID=YOUR_MERCHANT_ID_HERE
PAYWAY_API_KEY=your_secret_api_key_here   # ⚠️ NEVER commit this to version control

# ─── Application URLs ───
NEXT_PUBLIC_BASE_URL=http://localhost:3000
PAYWAY_RETURN_URL=http://localhost:3000/payment/return
PAYWAY_NOTIFY_URL=http://localhost:3000/api/payment/notify

# ─── Security ───
NEXTAUTH_SECRET=generate_with_openssl_rand_base64_32
NODE_ENV=development

📋 How to get your PayWay credentials

1. Log in to the ABA PayWay Sandbox Portal (or production portal).
2. Navigate to Settings → API Credentials.
3. Copy your Merchant ID and API Key.
4. Double-check that the API URL matches your target environment (Sandbox vs. Production).

🔗 Integration Guide

Payment Flow

sequenceDiagram
    autonumber
    participant User
    participant ProStore
    participant PayWay
    participant Webhook

    User->>ProStore: Initiate Checkout
    ProStore->>PayWay: POST /create (Order Details)
    PayWay-->>ProStore: Returns payment_url
    ProStore-->>User: Redirect to PayWay Checkout
    User->>PayWay: Complete Payment
    PayWay->>Webhook: POST notify (Payment Status)
    Webhook-->>ProStore: Verify & Update Order Status
    PayWay-->>User: Redirect to return_url

Loading

Key Files

File Path	Purpose
lib/payway.js	PayWay API utilities (create payment, check status)
pages/api/payment/create.js	Endpoint that initiates a PayWay payment request
pages/api/payment/notify.js	Secure webhook handler for PayWay callbacks
components/PaymentModal.tsx	Reusable, styled payment UI component
pages/payment/return.js	Post-payment result/success page

Creating a Payment (Example)

// lib/payway.js
export async function createPayment({ orderId, amount, currency = 'USD' }) {
  const res = await fetch(`${process.env.PAYWAY_API_URL}/payment/create`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PAYWAY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      merchant_id: process.env.PAYWAY_MERCHANT_ID,
      order_id: orderId,
      amount: parseFloat(amount).toFixed(2),
      currency,
      return_url: process.env.PAYWAY_RETURN_URL,
      notify_url: process.env.PAYWAY_NOTIFY_URL,
    }),
  });

  if (!res.ok) throw new Error('PayWay API error');
  return res.json();
}

📁 Project Structure

ProStore_PayWay-Intergration/
├── components/
│   └── PaymentModal.tsx        # Reusable payment UI component
├── lib/
│   └── payway.js               # PayWay API helpers and utilities
├── pages/
│   ├── api/
│   │   └── payment/
│   │       ├── create.js       # Initiate payment endpoint
│   │       └── notify.js       # Webhook handler endpoint
│   ├── payment/
│   │   └── return.js           # Payment result/success page
│   ├── _app.js                 # Next.js App entry point
│   └── index.js                # Home / Checkout page
├── styles/
│   ├── globals.css             # Global Tailwind directives
│   └── PaymentModal.module.css # Component-specific styles
├── .env.example                # Environment variable template
├── next.config.js              # Next.js configuration
├── package.json                # Project dependencies and scripts
├── tsconfig.json               # TypeScript configuration
└── README.md                   # You are here!

🛡 Security Checklist

Before deploying to production, ensure you have addressed the following:

• Never expose PAYWAY_API_KEY in client-side code or public repositories.
• Validate every webhook request (verify signatures if/when PayWay provides them).
• Enforce HTTPS in production for all endpoints, especially webhooks.
• Sanitize and validate all user input server-side before processing.
• Log payment events for auditing, but never log sensitive data (like full card details or raw API keys).
• Rotate API keys periodically via the PayWay merchant portal.
• Restrict notify_url to PayWay's documented IP ranges if your hosting provider allows IP whitelisting.

🩹 Troubleshooting

Error / Symptom	Likely Cause	Recommended Fix
401 Unauthorized	Invalid API key or Merchant ID	Verify credentials in the PayWay portal. Check for trailing spaces in .env.
Webhook not firing	notify_url is not publicly reachable	Use ngrok for local testing.
Redirect loop after payment	return_url mismatch	Ensure the URL matches your PayWay merchant settings exactly.
TypeScript errors	Missing types or misconfigured tsconfig	Run npm run type-check and review tsconfig.json.
CORS issues	API called from the wrong origin	Configure allowed origins in Next.js middleware or headers.

🌐 Testing webhooks locally with ngrok

# 1. Expose your local server to the internet
npx ngrok http 3000

# 2. Update your .env file with the generated URL
PAYWAY_NOTIFY_URL=https://<your-ngrok-id>.ngrok.io/api/payment/notify

Note: Remember to update the notify_url in your PayWay Merchant Portal as well, or ensure your local endpoint is used for the test transaction.

📚 Resources

Resource	Link
Sandbox Portal	checkout-sandbox.payway.com.kh
Production Portal	checkout.payway.com.kh
Developer Documentation	developer.payway.com.kh
Official Support	support@payway.com.kh

© 2026 ProStore · All rights reserved
Provided for educational and integration purposes. Commercial use requires compliance with ABA PayWay's terms of service.

Empowering Cambodian commerce — one seamless payment at a time. 🇰🇭