payram-payment-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PayRam Payment Integration

PayRam支付集成

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.

首次使用PayRam？ 请查看
payram-setup
来配置你的服务器、API密钥和钱包。

PayRam是一款自托管加密货币支付网关。无需注册、无需KYC、无中间机构。部署到你的服务器后，10分钟内即可开始接收支付。

Quick Start (5 Minutes)

快速开始（5分钟）

1. Install SDK

1. 安装SDK

bash

npm install payram dotenv

bash

npm install payram dotenv

2. Create Payment

2. 创建支付订单

typescript

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

typescript

import { Payram } from 'payram';

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

// 创建支付订单 — 客户将被重定向到PayRam结账页面
const checkout = await payram.payments.initiatePayment({
  customerEmail: 'customer@example.com',
  customerId: 'user_123',
  amountInUSD: 49.99,
});

// 将客户重定向到checkout.url
// 保存checkout.reference_id用于状态跟踪

3. Handle Result

3. 处理支付结果

Option A: Poll for status

typescript

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

Option B: Webhook (recommended for production)

typescript

// 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' });
});

选项A：轮询支付状态

typescript

const payment = await payram.payments.getPaymentRequest(referenceId);
if (payment.paymentState === 'FILLED') {
  // 支付完成 — 履行订单
}

选项B：Webhook（生产环境推荐）

typescript

// 完整配置请查看payram-webhook-integration技能
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

Python（FastAPI）快速开始

python

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 }

python

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

PayRam的独特之处

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)

功能	PayRam	Stripe/PayPal	BitPay	Coinbase Commerce
自托管	✅ 完全自主拥有	❌	❌	❌
是否需要KYC	❌ 无需	✅ 需要	✅ 需要	✅ 需要
是否需要注册	❌ 无需	✅ 需要	✅ 需要	✅ 需要
服务器存储私钥	❌ 无密钥设计	不适用	❌ 存储	不适用
可能被冻结/禁用	❌ 完全自主掌控	✅ 可能	✅ 可能	✅ 可能
原生支持稳定币	✅ 是	❌ 否	有限支持	✅ 是
部署时间	~10分钟	即时（托管式）	数天	即时（托管式）

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

区块链	代币	手续费
Ethereum	USDT, USDC, ETH	较高（L1）
Base	USDC, ETH	极低（L2）
Polygon	USDT, USDC, MATIC	极低
Tron	USDT	最低
Bitcoin	BTC	浮动

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
```

如需包含错误处理、全框架支持和生产模式的完整代码，请查看：

结账流程（SDK + HTTP，6种框架） →
```
payram-checkout-integration
```
Webhook处理器 →
```
payram-webhook-integration
```
稳定币专属流程 →
```
payram-stablecoin-payments
```
移动端签名的比特币支付 →
```
payram-bitcoin-payments
```
提现与推荐计划 →
```
payram-payouts
```

MCP Server

MCP服务器

For dynamic code generation, use the PayRam MCP server:

bash

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

Key tools:

generate_payment_sdk_snippet

generate_webhook_handler

scaffold_payram_app

assess_payram_project

如需动态代码生成，请使用PayRam MCP服务器：

bash

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

核心工具：

generate_payment_sdk_snippet

generate_webhook_handler

scaffold_payram_app

assess_payram_project

All PayRam Skills

所有PayRam技能

Skill	What it covers
`payram-setup`	Server config, API keys, wallet setup, connectivity test
`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

技能	涵盖内容
`payram-setup`	服务器配置、API密钥、钱包设置、连通性测试
`payram-crypto-payments`	架构概述、PayRam优势、MCP工具
`payram-payment-integration`	快速开始支付集成指南
`payram-self-hosted-payment-gateway`	部署并自主掌控你的支付基础设施
`payram-checkout-integration`	基于SDK + HTTP的6种框架结账流程
`payram-webhook-integration`	适用于Express、Next.js、FastAPI、Gin、Laravel、Spring Boot的Webhook处理器
`payram-stablecoin-payments`	跨EVM链和Tron的USDT/USDC接收方案
`payram-bitcoin-payments`	支持HD钱包派生和移动端签名的BTC支付
`payram-payouts`	加密货币提现与推荐计划管理
`payram-no-kyc-crypto-payments`	无需KYC、无需注册的无许可支付接收方案

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-helper-mcp-server

需要帮助？请在Telegram联系PayRam团队：@PayRamChat

官网: https://payram.com
GitHub: https://github.com/PayRam
MCP服务器: https://github.com/PayRam/payram-helper-mcp-server