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: '[email protected]',
  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
import crypto from 'crypto';

// PayRam signs the raw body: X-Payram-Signature: sha256=<hex HMAC-SHA256, keyed with the project API key>
app.post('/payram-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (req.get('X-Webhook-Test') === 'true') return res.json({ ok: true }); // unsigned payout ping

  const expected = Buffer.from(
    'sha256=' +
      crypto.createHmac('sha256', process.env.PAYRAM_API_KEY!).update(req.body).digest('hex'),
  );
  const received = Buffer.from(req.get('X-Payram-Signature') ?? '');
  if (expected.length !== received.length || !crypto.timingSafeEqual(expected, received)) {
    return res.status(401).send();
  }

  const payload = JSON.parse(req.body.toString('utf8')); // amounts are decimal strings
  if (payload.status === 'FILLED') {
    fulfillOrder(payload.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

Supported Chains & Tokens

Customers can also pay on Solana, Bitcoin, Tron (USDT) and BNB Chain through Smart Bridge rails, which settle as USDC on Base (no extra node to run).

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, connect the hosted PayRam MCP server at https://mcp.payram.com/mcp (it never holds your credentials).

Key tools: generate_payment_sdk_snippet, generate_webhook_handler, scaffold_payram_app, payram_setup_plan. assess_payram_project and the live data tools are available when you run the MCP locally (PAYRAM_MCP_MODE=local).

All PayRam Skills

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