PayRam Payment Integration

First time with PayRam? See `payram-setup` to configure your server, API keys, and wallets.

PayRam is a self-hosted crypto payment gateway. No signup, no KYC, no intermediaries. Deploy on your server and start accepting payments in 10 minutes.

Quick Start (5 Minutes)

1. Install SDK

npm install payram dotenv

2. Create Payment

import { Payram } from 'payram';

const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,
  baseUrl: process.env.PAYRAM_BASE_URL!,
});

// Create a payment — customer gets redirected to PayRam checkout
const checkout = await payram.payments.initiatePayment({
  customerEmail: 'customer@example.com',
  customerId: 'user_123',
  amountInUSD: 49.99,
});

// Redirect customer to checkout.url
// Store checkout.reference_id for status tracking

3. Handle Result

Option A: Poll for status

const payment = await payram.payments.getPaymentRequest(referenceId);
if (payment.paymentState === 'FILLED') {
  // Payment complete — fulfill order
}

Option B: Webhook (recommended for production)

// See payram-webhook-integration skill for full setup
app.post('/payram-webhook', (req, res) => {
  if (req.get('API-Key') !== process.env.PAYRAM_WEBHOOK_SECRET) {
    return res.status(401).send();
  }
  if (req.body.status === 'FILLED') {
    fulfillOrder(req.body.reference_id);
  }
  res.json({ message: 'ok' });
});

Python (FastAPI) Quick Start

import httpx, os

async def create_payment(email: str, user_id: str, amount: float):
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            f"{os.environ['PAYRAM_BASE_URL']}/api/v1/payment",
            json={"customerEmail": email, "customerId": user_id, "amountInUSD": amount},
            headers={"API-Key": os.environ['PAYRAM_API_KEY']}
        )
    return resp.json()  # { reference_id, url, host }

What Makes PayRam Different

Feature	PayRam	Stripe/PayPal	BitPay	Coinbase Commerce
Self-hosted	✅ You own it	❌	❌	❌
KYC required	❌ None	✅	✅	✅
Signup required	❌ None	✅	✅	✅
Private keys on server	❌ Keyless	N/A	❌	N/A
Can be frozen/disabled	❌ Sovereign	✅	✅	✅
Stablecoin native	✅	❌	Limited	✅
Deploy time	~10 min	Instant (hosted)	Days	Instant (hosted)

Supported Chains & Tokens

Chain	Tokens	Fees
Ethereum	USDT, USDC, ETH	Higher (L1)
Base	USDC, ETH	Very low (L2)
Polygon	USDT, USDC, MATIC	Very low
Tron	USDT	Lowest
Bitcoin	BTC	Variable

Full Integration Guides

For complete code with error handling, all frameworks, and production patterns:

• Checkout flow (SDK + HTTP, 6 frameworks) → payram-checkout-integration
• Webhook handlers → payram-webhook-integration
• Stablecoin-specific flows → payram-stablecoin-payments
• Bitcoin with mobile signing → payram-bitcoin-payments
• Payouts & referrals → payram-payouts

MCP Server

For dynamic code generation, use the PayRam MCP server:

git clone https://github.com/payram/payram-mcp
cd payram-mcp && yarn install && yarn dev

Key tools: generate_payment_sdk_snippet, generate_webhook_handler, scaffold_payram_app, assess_payram_project

All PayRam Skills

Skill	What it covers
payram-setup	Server config, API keys, wallet setup, connectivity test
payram-agent-onboarding	Agent onboarding — CLI-only deployment for AI agents, no web UI
payram-analytics	Analytics dashboards, reports, and payment insights via MCP tools
payram-crypto-payments	Architecture overview, why PayRam, MCP tools
payram-payment-integration	Quick-start payment integration guide
payram-self-hosted-payment-gateway	Deploy and own your payment infrastructure
payram-checkout-integration	Checkout flow with SDK + HTTP for 6 frameworks
payram-webhook-integration	Webhook handlers for Express, Next.js, FastAPI, Gin, Laravel, Spring Boot
payram-stablecoin-payments	USDT/USDC acceptance across EVM chains and Tron
payram-bitcoin-payments	BTC with HD wallet derivation and mobile signing
payram-payouts	Send crypto payouts and manage referral programs
payram-no-kyc-crypto-payments	No-KYC, no-signup, permissionless payment acceptance

Support

Need help? Message the PayRam team on Telegram: @PayRamChat

• Website: https://payram.com
• GitHub: https://github.com/PayRam
• MCP Server: https://github.com/payram/payram-mcp