Implementing the Payment Form

Use this guide & video to get your Payram-integrated Next.js app up and running, whether you’re developing locally or deploying to production.

---

1. Prerequisites

Before you begin, ensure you have the following installed:

• Node.js & npm

  • Recommended: Node.js v18.x or later (includes npm).

  • Verify:

    node --version
    npm --version

• Git

  • To clone the repository.

  • Verify:

    git --version

• Optional Tools

  • VS Code (or another IDE) with ESLint & Prettier extensions.

  • Postman or curl for testing webhooks and API endpoints.

---

2. Clone the Repository

git clone https://github.com/iam-joey/api-payram-integration.git
cd api-payram-integration

---

3. Configure Environment Variables

1. Copy the example file and rename it:

   cp .env.example .env

2. Open .env in your editor and set: (yourdomain is where your PayRam Server is hosted)

   PAYRAM_API_URL="http://yourdomain:8080/api/v1/payment"
   API_KEY="your-payram-api-key-here"

   • PAYRAM_API_URL The base URL for Payram’s API. Keep as-is for local testing or update if your Payram server is hosted elsewhere.

   • API_KEY Your secret key provided by Payram — required for all API requests.

Tip: Do not commit .env to source control. Add it to .gitignore if it isn’t already.

---

4. Install Dependencies

From the project root, run:

npm install

This will install everything listed in package.json.

---

5. Run the Development Server

Start your app in development mode:

npm run dev

• Open your browser at http://localhost:3000.

• The page auto-reloads on file changes.

---

6. Project Overview

6.1 Frontend: src/app/page.tsx

A client-side Next.js component handling:

• Customer ID (auto-generated, read-only)

• Payment Amount (USD)

• Customer Email

Features:

• Basic client-side validation

• POST to /api/initiate-payment on submit

• Toast notifications for success, error, or redirection

• Opens Payram payment URL in a new tab when provided

6.2 Backend API Routes

All routes live under src/app/api/:

Endpoint	File	Purpose
POST /api/initiate-payment	src/app/api/initiate-payment/route.ts	Starts a Payram transaction; returns a redirect URL.
POST /api/v1/payment/webhook	src/app/api/v1/payment/webhook/route.ts	Receives Payram webhook events to update transaction status.

---

7. Testing Webhooks Locally

To test the webhook endpoint before deploying:

1. Install ngrok (or similar) to expose your localhost:3000:

   npm install -g ngrok
   ngrok http 3000

2. Copy the generated https://xxxx.ngrok.io URL.

3. In your Payram dashboard, configure the webhook URL to:

   https://xxxx.ngrok.io/api/v1/payment/webhook

4. Trigger a payment on the frontend and observe webhook logs in your terminal.

---

8. Building for Production

1. Build:

   npm run build

2. Start Production Server:

   npm start

3. Environment Variables:

   • Use a .env.production or your hosting provider’s secret management.

---

9. Deploying on Vercel

1. Push your repo to GitHub (if not already).

2. Sign in at vercel.com and “Import Project” from GitHub.

3. In Project Settings, add Environment Variables (PAYRAM_API_URL, API_KEY).

4. Deploy — Vercel auto-builds and provides you a live URL.

For detailed Vercel instructions, see their Next.js Deployment Docs.

---

With these steps, you should have a fully operational local development environment, webhook testing setup, and a clear path to production deployment. Happy coding!