This skill provides instructions for scaffolding complete starter applications with Payram integration. Instead of adding Payram to existing projects, you'll generate new applications from scratch with payments, payouts, and webhooks pre-configured. Each scaffold includes a web console for testing functionality without writing frontend code.

Use this skill when you need to:

• Create a new project with Payram integration from scratch
• Build proof-of-concept or demo applications quickly
• Learn Payram API patterns through working examples
• Generate reference implementations for your team
• Prototype new features before adding to production code

Before starting, ensure you have:

• Completed the setup-payram skill (understand environment configuration)
• Chosen your target framework (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot)
• Development tools installed (Node.js/Python/PHP/Go/Java)
• Basic familiarity with your chosen framework

---

Part 1: Understanding Scaffold Structure

#### 1.1 What's Included

All scaffolds provide:

1. Environment Configuration

- .env.example with Payram variables

- Configuration loading/validation

1. Payment Endpoints

- POST /api/payments/create - Create payment

- GET /api/payments/:referenceId - Check status

1. Payout Endpoints

- POST /api/payouts/create - Create payout

- GET /api/payouts/:id - Check status

1. Webhook Handler (optional)

- POST /api/payram/webhook - Receive events

1. Web Console (browser UI)

- Test payments visually

- Test payouts visually

- View API responses

1. Package Configuration

- Dependencies (Payram SDK, framework, etc.)

- Scripts for running/building

#### 1.2 Directory Structures

Express:

```

payram-express-starter/

├── package.json

├── .env.example

├── index.js

└── public/

└── index.html

```

Next.js:

```

payram-nextjs-starter/

├── package.json

├── .env.example

├── next.config.js

├── app/

│ ├── page.tsx

│ └── api/

│ ├── payments/

│ │ ├── create/route.ts

│ │ └── [referenceId]/route.ts

│ ├── payouts/

│ │ ├── create/route.ts

│ │ └── [id]/route.ts

│ └── payram/

│ └── webhook/route.ts

└── lib/

└── payram.ts

```

FastAPI:

```

payram-fastapi-starter/

├── requirements.txt

├── .env.example

├── main.py

└── templates/

└── index.html

```

Laravel:

```

payram-laravel-starter/

├── composer.json

├── .env.example

├── routes/

│ └── api.php

├── app/

│ └── Http/

│ └── Controllers/

│ └── PayramController.php

└── resources/

└── views/

└── console.blade.php

```

Gin:

```

payram-gin-starter/

├── go.mod

├── .env.example

├── main.go

├── handlers/

│ └── payram.go

└── static/

└── index.html

```

Spring Boot:

```

payram-spring-boot-starter/

├── pom.xml

├── .env.example

├── src/

│ └── main/

│ ├── java/com/example/payram/

│ │ ├── PayramApplication.java

│ │ └── controller/

│ │ └── PayramController.java

│ └── resources/

│ ├── application.properties

│ └── static/

│ └── index.html

```

---

Part 2: Framework-Specific Instructions

#### 2.1 Express Scaffold

Step 1: Create Directory Structure

```bash

mkdir payram-express-starter

cd payram-express-starter

```

Step 2: Initialize Node Project

```bash

npm init -y

```

Step 3: Install Dependencies

```bash

npm install express cors dotenv payram

```

Step 4: Create .env.example

File: .env.example

```bash

PAYRAM_BASE_URL=https://your-merchant.payram.com

PAYRAM_API_KEY=pk_test_your_api_key_here

PORT=3000

```

Step 5: Create Main Server File

File: index.js

```javascript

import express from 'express';

import cors from 'cors';

import dotenv from 'dotenv';

import { Payram } from 'payram';

dotenv.config();

const app = express();

app.use(cors());

app.use(express.json());

app.use(express.static('public'));

const payram = new Payram({

apiKey: process.env.PAYRAM_API_KEY,

baseUrl: process.env.PAYRAM_BASE_URL,

});

// Payment endpoints

app.post('/api/payments/create', async (req, res) => {

try {

const {

amount = 1,

customerEmail = 'demo@example.com',

customerId = 'demo-customer',

} = req.body;

const checkout = await payram.payments.initiatePayment({

amountInUSD: Number(amount),

customerEmail,

customerId,

});

res.json(checkout);

} catch (error) {

console.error('Payment creation failed:', error);

res.status(500).json({

error: 'payment_create_failed',

details: error.message,

});

}

});

app.get('/api/payments/:referenceId', async (req, res) => {

try {

const payment = await payram.payments.getPaymentRequest(req.params.referenceId);

res.json(payment);

} catch (error) {

console.error('Payment status check failed:', error);

res.status(500).json({

error: 'payment_status_failed',

details: error.message,

});

}

});

// Payout endpoints

app.post('/api/payouts/create', async (req, res) => {

try {

const {

amount = '1',

currencyCode = 'USDT',

blockchainCode = 'ETH',

customerID = 'demo-customer',

email = 'merchant@example.com',

toAddress = '0xfeedfacecafebeefdeadbeefdeadbeefdeadbeef',

mobileNumber = '+15555555555',

residentialAddress = '123 Main St, City, Country',

} = req.body;

const payout = await payram.payouts.createPayout({

customerID,

email,

blockchainCode,

currencyCode,

amount: String(amount),

toAddress,

mobileNumber,

residentialAddress,

});

res.json(payout);

} catch (error) {

console.error('Payout creation failed:', error);

res.status(500).json({

error: 'payout_create_failed',

details: error.message,

});

}

});

app.get('/api/payouts/:id', async (req, res) => {

try {

const payout = await payram.payouts.getPayoutById(Number(req.params.id));

res.json(payout);

} catch (error) {

console.error('Payout status check failed:', error);

res.status(500).json({

error: 'payout_status_failed',

details: error.message,

});

}

});

// Webhook endpoint

app.post('/api/payram/webhook', (req, res) => {

console.log('Payram webhook event received:', req.body);

// TODO: Validate API-Key header

// TODO: Process event based on status

res.json({ message: 'Webhook received successfully' });

});

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {

console.log(Payram Express starter running on http://localhost:${PORT});

console.log(Open http://localhost:${PORT} to access the test console);

});

```

Step 6: Create Web Console

File: public/index.html

```html

```

Step 7: Update package.json

```json

{

"name": "payram-express-starter",

"version": "1.0.0",

"type": "module",

"scripts": {

"start": "node index.js",

"dev": "node --watch index.js"

},

"dependencies": {

"express": "^4.18.2",

"cors": "^2.8.5",

"dotenv": "^16.3.1",

"payram": "latest"

}

}

```

Step 8: Run Application

```bash

# Copy .env.example to .env

cp .env.example .env

# Edit .env with real credentials

nano .env

# Start server

npm start

# Open browser

open http://localhost:3000

```

---

#### 2.2 Next.js Scaffold

Quick Start:

```bash

# Create Next.js app

npx create-next-app@latest payram-nextjs-starter --typescript --tailwind --app --no-src-dir

cd payram-nextjs-starter

# Install Payram SDK

npm install payram

# Create .env.local

cat > .env.local << 'EOF'

PAYRAM_BASE_URL=https://your-merchant.payram.com

PAYRAM_API_KEY=pk_test_your_api_key_here

EOF

```

Create API Routes:

File: app/api/payments/create/route.ts

```typescript

import { NextRequest, NextResponse } from 'next/server';

import { Payram } from 'payram';

const payram = new Payram({

apiKey: process.env.PAYRAM_API_KEY!,

baseUrl: process.env.PAYRAM_BASE_URL!,

});

export async function POST(request: NextRequest) {

try {

const {

amount = 1,

customerEmail = 'demo@example.com',

customerId = 'demo',

} = await request.json();

const checkout = await payram.payments.initiatePayment({

amountInUSD: Number(amount),

customerEmail,

customerId,

});

return NextResponse.json(checkout);

} catch (error: any) {

return NextResponse.json(

{ error: 'payment_create_failed', details: error.message },

{ status: 500 },

);

}

}

```

File: app/api/payments/[referenceId]/route.ts

```typescript

import { NextRequest, NextResponse } from 'next/server';

import { Payram } from 'payram';

const payram = new Payram({

apiKey: process.env.PAYRAM_API_KEY!,

baseUrl: process.env.PAYRAM_BASE_URL!,

});

export async function GET(request: NextRequest, { params }: { params: { referenceId: string } }) {

try {

const payment = await payram.payments.getPaymentRequest(params.referenceId);

return NextResponse.json(payment);

} catch (error: any) {

return NextResponse.json(

{ error: 'payment_status_failed', details: error.message },

{ status: 500 },

);

}

}

```

Similar patterns for payouts and webhooks.

---

#### 2.3 FastAPI Scaffold

Quick Start:

```bash

mkdir payram-fastapi-starter

cd payram-fastapi-starter

# Create requirements.txt

cat > requirements.txt << 'EOF'

fastapi==0.104.1

uvicorn[standard]==0.24.0

python-dotenv==1.0.0

payram==1.0.0

EOF

# Install dependencies

pip install -r requirements.txt

# Create .env

cat > .env << 'EOF'

PAYRAM_BASE_URL=https://your-merchant.payram.com

PAYRAM_API_KEY=pk_test_your_api_key_here

EOF

```

File: main.py

```python

from fastapi import FastAPI, HTTPException

from fastapi.middleware.cors import CORSMiddleware

from fastapi.staticfiles import StaticFiles

from fastapi.responses import FileResponse

from pydantic import BaseModel

import os

from dotenv import load_dotenv

load_dotenv()

app = FastAPI(title="Payram FastAPI Starter")

app.add_middleware(

CORSMiddleware,

allow_origins=["*"],

allow_methods=["*"],

allow_headers=["*"],

)

# TODO: Initialize Payram client here

# from payram import Payram

# payram = Payram(

# api_key=os.getenv('PAYRAM_API_KEY'),

# base_url=os.getenv('PAYRAM_BASE_URL')

# )

class PaymentRequest(BaseModel):

amount: float = 1.0

customerEmail: str = "demo@example.com"

customerId: str = "demo-customer"

class PayoutRequest(BaseModel):

amount: str = "1"

currencyCode: str = "USDT"

blockchainCode: str = "ETH"

customerID: str = "demo-customer"

email: str = "merchant@example.com"

toAddress: str = "0xfeedfacecafebeefdeadbeefdeadbeefdeadbeef"

mobileNumber: str = "+15555555555"

residentialAddress: str = "123 Main St"

@app.post("/api/payments/create")

async def create_payment(req: PaymentRequest):

try:

# TODO: Call payram.payments.initiate_payment(...)

return {"message": "Payment endpoint - implement with Payram SDK"}

except Exception as e:

raise HTTPException(status_code=500, detail=str(e))

@app.get("/api/payments/{reference_id}")

async def get_payment_status(reference_id: str):

try:

# TODO: Call payram.payments.get_payment_request(reference_id)

return {"message": "Payment status endpoint - implement with Payram SDK"}

except Exception as e:

raise HTTPException(status_code=500, detail=str(e))

@app.post("/api/payouts/create")

async def create_payout(req: PayoutRequest):

try:

# TODO: Call payram.payouts.create_payout(...)

return {"message": "Payout endpoint - implement with Payram SDK"}

except Exception as e:

raise HTTPException(status_code=500, detail=str(e))

@app.get("/api/payouts/{payout_id}")

async def get_payout_status(payout_id: int):

try:

# TODO: Call payram.payouts.get_payout_by_id(payout_id)

return {"message": "Payout status endpoint - implement with Payram SDK"}

except Exception as e:

raise HTTPException(status_code=500, detail=str(e))

@app.post("/api/payram/webhook")

async def handle_webhook(payload: dict):

print("Webhook received:", payload)

return {"message": "Webhook received successfully"}

if __name__ == "__main__":

import uvicorn

uvicorn.run(app, host="0.0.0.0", port=8000)

```

Run:

```bash

python main.py

# or

uvicorn main:app --reload

```

---

Part 3: Common Patterns

#### 3.1 Error Handling

All scaffolds should include:

```javascript

try {

const result = await payram.payments.initiatePayment(...);

return success(result);

} catch (error) {

console.error('Payram API error:', error);

return error_response({

error: 'operation_failed',

details: error.message,

// Don't expose internal errors to clients

});

}

```

#### 3.2 Environment Validation

Check configuration on startup:

```javascript

if (!process.env.PAYRAM_BASE_URL || !process.env.PAYRAM_API_KEY) {

console.error('ERROR: Payram environment variables not configured');

console.error('Please copy .env.example to .env and fill in your credentials');

process.exit(1);

}

```

#### 3.3 CORS Configuration

Allow frontend to call APIs:

```javascript

app.use(

cors({

origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',

methods: ['GET', 'POST'],

credentials: true,

}),

);

```

---

1. Never Commit Credentials

```bash

# Add to .gitignore

echo ".env" >> .gitignore

echo ".env.local" >> .gitignore

# Always provide .env.example

cp .env .env.example

# Replace values with placeholders in .env.example

```

2. Use Environment-Specific Configuration

```

.env.development # Local development

.env.test # Testing

.env.production # Production (managed via deployment)

```

3. Add Health Check Endpoint

```javascript

app.get('/health', (req, res) => {

res.json({

status: 'healthy',

timestamp: new Date().toISOString(),

payramConfigured: !!(process.env.PAYRAM_BASE_URL && process.env.PAYRAM_API_KEY),

});

});

```

4. Log API Interactions

```javascript

console.log('[Payram] Creating payment:', {

amount,

customerId,

timestamp: new Date().toISOString(),

});

```

5. Validate Input

```javascript

if (!amount || amount <= 0) {

return res.status(400).json({ error: 'Invalid amount' });

}

if (!customerId || customerId.trim().length === 0) {

return res.status(400).json({ error: 'Customer ID required' });

}

```

---

Port Already in Use

Error: EADDRINUSE: address already in use

Solution:

```bash

# Find process using port

lsof -ti:3000

# Kill process

kill -9 $(lsof -ti:3000)

# Or use different port

PORT=3001 npm start

```

Module Not Found

Error: Cannot find module 'payram'

Solution:

```bash

# Reinstall dependencies

rm -rf node_modules package-lock.json

npm install

```

Environment Variables Not Loading

Cause: .env file not in project root or not loaded.

Solution:

```bash

# Check file exists

ls -la .env

# Verify dotenv is loaded

# Add to top of your main file:

require('dotenv').config(); // CommonJS

# or

import 'dotenv/config'; // ESM

```

---

• setup-payram: Configure credentials after scaffolding
• integrate-payments: Understand payment patterns used in scaffolds
• integrate-payouts: Understand payout patterns
• handle-webhooks: Enhance webhook handlers in scaffolds

---

You now know how to scaffold complete Payram applications:

1. Express: Node.js with simple file structure
2. Next.js: React with App Router and API routes
3. FastAPI: Python async web framework
4. Laravel: PHP MVC framework (similar patterns)
5. Gin: Go web framework (similar patterns)
6. Spring Boot: Java enterprise framework (similar patterns)

All scaffolds include:

• Payment creation and status checking
• Payout creation and status checking
• Webhook handling (optional)
• Web console for testing
• Environment configuration
• Error handling

Next Steps:

• Choose your framework
• Follow framework-specific instructions
• Copy .env.example to .env and configure
• Run the application
• Test via web console
• Customize for your needs