payram-bitcoin-payments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PayRam Bitcoin Payments

PayRam 比特币支付

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

PayRam supports on-chain Bitcoin with a unique architecture: HD wallet derivation for deposits, mobile app signing for sweeps—no private keys ever touch the server.

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

PayRam支持链上比特币支付，采用独特架构：通过HD钱包派生存款地址，通过移动应用签名完成扫款——私钥绝不会接触服务器。

Bitcoin vs EVM Architecture

比特币与EVM架构对比

Aspect	EVM Chains	Bitcoin
Deposit addresses	Smart contract generated	HD wallet derived
Sweep mechanism	Automated smart contract	Manual mobile app approval
Key storage	Keyless (contract-based)	Seed phrase on mobile only
Confirmation time	~15 sec - 2 min	~10-60 min

维度	EVM链	比特币
存款地址生成方式	智能合约生成	HD钱包派生
扫款机制	自动化智能合约	手动移动应用批准
密钥存储	无密钥（基于合约）	助记词仅存储在移动设备
确认时间	~15秒 - 2分钟	~10-60分钟

Setup Overview

配置概述

Step 1: Configure Bitcoin in PayRam Dashboard

步骤1：在PayRam控制台配置比特币

Navigate to Wallet Management → Bitcoin & Other Networks
Click Add Cold Wallet
Enter your Bitcoin cold wallet address (where funds will sweep to)

导航至钱包管理 → 比特币及其他网络
点击添加冷钱包
输入你的比特币冷钱包地址（资金将扫款至该地址）

Step 2: Link Mobile App

步骤2：关联移动应用

The PayRam Merchant mobile app handles Bitcoin signing:

Download PayRam Merchant app (iOS/Android)
In PayRam dashboard: Settings → Accounts → Connect to PayRam Mobile App
Scan QR code with mobile app
Set up device passcode/biometrics

PayRam Merchant移动应用负责处理比特币签名：

下载PayRam Merchant应用（iOS/Android）
在PayRam控制台中：设置 → 账户 → 连接至PayRam移动应用
使用移动应用扫描二维码
设置设备密码/生物识别验证

Step 3: Enter Seed Phrase (Mobile Only)

步骤3：输入助记词（仅在移动设备操作）

Open PayRam Merchant app
Select your configured BTC wallet
Click Link Wallet
Enter 12-word Bitcoin seed phrase

Security: Seed phrase is encrypted and stored only on your mobile device. Never transmitted to server.

打开PayRam Merchant应用
选择你已配置的BTC钱包
点击关联钱包
输入12词比特币助记词

安全说明：助记词会被加密并仅存储在你的移动设备中，绝不会传输至服务器。

Step 4: Approve Sweeps via Mobile

步骤4：通过移动应用批准扫款

When deposits accumulate:

Open app → Signing Requests → Pending
Review batch: deposit addresses, amounts, fees
Approve batch to sweep funds to cold wallet
Monitor progress in In Progress tab
View completed sweeps in History

当存款累计到一定程度时：

打开应用 → 签名请求 → 待处理
审核批次信息：存款地址、金额、手续费
批准批次以将资金扫款至冷钱包
在处理中标签页监控进度
在历史记录标签页查看已完成的扫款

Payment Flow

支付流程

1. Customer requests payment
2. PayRam derives unique BTC address from your seed (HD wallet)
3. Customer sends BTC to deposit address
4. PayRam detects transaction, waits for confirmations
5. Webhook fires: payment.pending → payment.successful
6. Deposits batch for sweep
7. You approve sweep in mobile app
8. Funds move to your cold wallet

1. 客户发起支付请求
2. PayRam从你的助记词（HD钱包）派生唯一的BTC地址
3. 客户向该存款地址发送BTC
4. PayRam检测到交易，等待确认
5. 触发Webhook：payment.pending → payment.successful
6. 存款将被批量处理以进行扫款
7. 你在移动应用中批准扫款
8. 资金转移至你的冷钱包

Integration

集成方式

Bitcoin payments use the same API as stablecoin/crypto payments:

javascript

const response = await axios.post(
  `${PAYRAM_BASE_URL}/api/v1/payment`,
  {
    customerEmail: "customer@example.com",
    customerId: "user_123",
    amountInUSD: 50  // PayRam shows BTC equivalent
  },
  { headers: { 'API-Key': PAYRAM_API_KEY } }
);

// User redirected to payment page
// Can select Bitcoin as payment method

比特币支付使用与稳定币/加密货币支付相同的API：

javascript

const response = await axios.post(
  `${PAYRAM_BASE_URL}/api/v1/payment`,
  {
    customerEmail: "customer@example.com",
    customerId: "user_123",
    amountInUSD: 50  // PayRam会显示对应的BTC金额
  },
  { headers: { 'API-Key': PAYRAM_API_KEY } }
);

// 用户将被重定向至支付页面
// 可选择比特币作为支付方式

Webhook Events

Webhook事件

json

{
  "type": "payment.successful",
  "data": {
    "reference_id": "abc123",
    "chain": "bitcoin",
    "token": "BTC",
    "amountInUSD": 50,
    "tokenAmount": "0.00052",
    "txHash": "abc123...",
    "confirmations": 3
  }
}

json

{
  "type": "payment.successful",
  "data": {
    "reference_id": "abc123",
    "chain": "bitcoin",
    "token": "BTC",
    "amountInUSD": 50,
    "tokenAmount": "0.00052",
    "txHash": "abc123...",
    "confirmations": 3
  }
}

HD Wallet Derivation

HD钱包派生

PayRam uses BIP44 derivation to generate unique addresses:

Master seed: Your 12-word phrase (mobile only)
Derivation path:
```
m/44'/0'/0'/0/n
```
Result: Unlimited unique deposit addresses, all controlled by same seed

Benefits:

Each customer/transaction gets unique address
No address reuse
Single seed controls all deposits
Cold wallet receives all swept funds

PayRam使用BIP44派生规则生成唯一地址：

主助记词：你的12词短语（仅存储在移动设备）
派生路径：
```
m/44'/0'/0'/0/n
```
结果：生成无限多的唯一存款地址，全部由同一助记词控制

优势：

每个客户/交易都有唯一地址
避免地址重复使用
单个助记词控制所有存款
冷钱包接收所有扫款资金

Confirmation Requirements

确认要求

Bitcoin requires more confirmations due to longer block times:

Amount	Recommended Confirmations
< $100	1 confirmation (~10 min)
$100 - $1000	3 confirmations (~30 min)
> $1000	6 confirmations (~60 min)

Configure thresholds in PayRam dashboard.

由于比特币区块时间更长，需要更多的确认数：

金额	推荐确认数
< 100美元	1次确认（约10分钟）
100 - 1000美元	3次确认（约30分钟）
> 1000美元	6次确认（约60分钟）

可在PayRam控制台中配置阈值。

Mobile App Security

移动应用安全

What's on the server:

Extended public key (xpub) for address generation
No private keys, no seed phrase

What's on mobile:

Encrypted seed phrase
Signing capability
Protected by device security (PIN, biometrics)

Sweep approval:

Each batch requires explicit mobile approval
Review amounts, addresses, fees before signing
Audit trail of all approvals

服务器端存储内容：

用于地址生成的扩展公钥（xpub）
无私钥、无助记词

移动设备存储内容：

加密后的助记词
签名权限
受设备安全机制（PIN码、生物识别）保护

扫款批准：

每批扫款都需要明确的移动应用批准
签名前可审核金额、地址、手续费
所有批准操作都有审计记录

Compared to Other Solutions

与其他方案对比

Feature	PayRam	BTCPay Server	BitPay
Self-hosted	✅	✅	❌
Mobile signing	✅	❌	❌
Stablecoin support	✅	Limited	✅
No keys on server	✅	❌	❌

功能	PayRam	BTCPay Server	BitPay
自托管	✅	✅	❌
移动签名	✅	❌	❌
稳定币支持	✅	有限	✅
服务器无密钥	✅	❌	❌

MCP Server Tools

MCP服务器工具

Standard payment tools work for Bitcoin:

Tool	Purpose
`generate_payment_sdk_snippet`	Payment creation
`generate_webhook_handler`	BTC payment events
`scaffold_payram_app`	Full app with BTC support

标准支付工具同样适用于比特币：

工具	用途
`generate_payment_sdk_snippet`	创建支付请求
`generate_webhook_handler`	处理BTC支付事件
`scaffold_payram_app`	搭建支持BTC的完整应用

Troubleshooting

故障排除

Deposits not detected: Check Bitcoin node sync status in PayRam dashboard.

Sweep pending too long: Open mobile app, check Signing Requests → Pending.

Address derivation issues: Verify seed phrase matches expected xpub.

存款未被检测到：在PayRam控制台中检查比特币节点同步状态。

扫款待处理时间过长：打开移动应用，查看“签名请求 → 待处理”。

地址派生问题：验证助记词是否与预期的xpub匹配。

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链和波场链上接受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