Back to Details

payram-payouts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PayRam Payouts & Referrals

PayRam 加密货币付款与推荐计划

First time with PayRam? See 
payram-setup
 to configure your server, API keys, and wallets.
PayRam uniquely combines inbound payments with outbound payouts and built-in referral tracking—a complete payment + growth stack in one self-hosted platform.
首次使用PayRam？ 请查看
payram-setup
来配置你的服务器、API密钥和钱包。
PayRam独特地将入金支付、出金付款与内置推荐追踪功能相结合——是一个集支付与增长于一体的自托管平台。

Why This Matters

为何选择PayRam

Most payment processors handle only inbound. Payouts require separate integrations (Wise, PayPal, manual transfers). Referral tracking needs yet another tool (FirstPromoter, Rewardful).
PayRam consolidates all three:
  • Accept payments (deposits)
  • Send payouts (withdrawals, rewards)
  • Track referrals (campaigns, attribution, automated rewards)
大多数支付处理器仅处理入金业务。出金付款需要单独集成（如Wise、PayPal、手动转账）。推荐追踪则需要另一款工具（如FirstPromoter、Rewardful）。
PayRam将这三者整合在一起：
  • 接收付款（入金）
  • 发送付款（提现、奖励）
  • 追踪推荐（活动、归因、自动奖励）

Payouts

付款功能

Payout Lifecycle

付款生命周期

Payouts progress through these states:
  1. pending-otp-verification — Awaiting OTP confirmation (if required)
  2. pending-approval — Awaiting manual approval (if thresholds require it)
  3. pending — Queued for processing
  4. initiated — Processing has started
  5. sent — Transaction broadcast to blockchain
  6. processed — Confirmed on blockchain
  7. failed — Transaction failed (insufficient balance, invalid address)
  8. rejected — Manually rejected by admin
  9. cancelled — Cancelled before processing
付款会经历以下状态：
  1. pending-otp-verification — 等待OTP确认（若需验证）
  2. pending-approval — 等待手动审批（若金额达到阈值）
  3. pending — 等待处理
  4. initiated — 处理已开始
  5. sent — 交易已广播至区块链
  6. processed — 交易已在区块链上确认
  7. failed — 交易失败（余额不足、地址无效）
  8. rejected — 管理员手动拒绝
  9. cancelled — 处理前已取消

Creating Payouts with SDK

使用SDK创建付款

typescript
import { Payram, CreatePayoutRequest, MerchantPayout, isPayramSDKError } from 'payram';

const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,
  baseUrl: process.env.PAYRAM_BASE_URL!,
  config: {
    timeoutMs: 10_000,
    maxRetries: 2,
  },
});

export async function createPayout(payload: CreatePayoutRequest): Promise<MerchantPayout> {
  try {
    const payout = await payram.payouts.createPayout(payload);
    console.log('Payout created:', {
      id: payout.id,
      status: payout.status,
      blockchain: payout.blockchainCode,
      currency: payout.currencyCode,
      amount: payout.amount,
    });
    return payout;
  } catch (error) {
    if (isPayramSDKError(error)) {
      console.error('Payram Error:', {
        status: error.status,
        requestId: error.requestId,
        isRetryable: error.isRetryable,
      });
    }
    throw error;
  }
}

// Example invocation
await createPayout({
  email: 'merchant@example.com',
  blockchainCode: 'ETH',
  currencyCode: 'USDC',
  amount: '125.50', // MUST be string, not number
  toAddress: '0xfeedfacecafebeefdeadbeefdeadbeefdeadbeef',
  customerID: 'cust_123',
  mobileNumber: '+15555555555', // Optional, E.164 format required
  residentialAddress: '1 Market St, San Francisco, CA 94105', // Optional
});
typescript
import { Payram, CreatePayoutRequest, MerchantPayout, isPayramSDKError } from 'payram';

const payram = new Payram({
  apiKey: process.env.PAYRAM_API_KEY!,
  baseUrl: process.env.PAYRAM_BASE_URL!,
  config: {
    timeoutMs: 10_000,
    maxRetries: 2,
  },
});

export async function createPayout(payload: CreatePayoutRequest): Promise<MerchantPayout> {
  try {
    const payout = await payram.payouts.createPayout(payload);
    console.log('Payout created:', {
      id: payout.id,
      status: payout.status,
      blockchain: payout.blockchainCode,
      currency: payout.currencyCode,
      amount: payout.amount,
    });
    return payout;
  } catch (error) {
    if (isPayramSDKError(error)) {
      console.error('Payram Error:', {
        status: error.status,
        requestId: error.requestId,
        isRetryable: error.isRetryable,
      });
    }
    throw error;
  }
}

// Example invocation
await createPayout({
  email: 'merchant@example.com',
  blockchainCode: 'ETH',
  currencyCode: 'USDC',
  amount: '125.50', // MUST be string, not number
  toAddress: '0xfeedfacecafebeefdeadbeefdeadbeefdeadbeef',
  customerID: 'cust_123',
  mobileNumber: '+15555555555', // Optional, E.164 format required
  residentialAddress: '1 Market St, San Francisco, CA 94105', // Optional
});

Payout Fields

付款字段说明

FieldTypeNotes
email
stringMerchant email associated with payout
blockchainCode
stringNetwork code: 'ETH', 'BTC', 'MATIC', etc.
currencyCode
stringToken code: 'USDC', 'USDT', 'BTC', etc.
amount
stringAmount as string (e.g., '125.50'). NOT a number.
toAddress
stringRecipient wallet address
customerID
stringYour internal reference ID
mobileNumber
stringOptional. E.164 format: +15555555555
residentialAddress
stringOptional. Recipient address (compliance)
Critical: Amount must be a string. JavaScript numbers lose precision with decimals.
字段类型备注
email
string与付款关联的商家邮箱
blockchainCode
string网络代码：'ETH'、'BTC'、'MATIC'等
currencyCode
string代币代码：'USDC'、'USDT'、'BTC'等
amount
string金额需为字符串格式（如'125.50'），不能是数字类型。
toAddress
string收款钱包地址
customerID
string你的内部参考ID
mobileNumber
string可选，需符合E.164格式：+15555555555
residentialAddress
string可选，收款方地址（合规要求）
重要提示：金额必须为字符串。JavaScript数字在处理小数时会丢失精度。

Check Payout Status

检查付款状态

typescript
export async function getPayoutStatus(payoutId: number): Promise<MerchantPayout> {
  const payout = await payram.payouts.getPayoutById(payoutId);
  console.log('Payout status:', {
    id: payout.id,
    status: payout.status,
    transactionHash: payout.transactionHash,
    amount: payout.amount,
  });
  return payout;
}
typescript
export async function getPayoutStatus(payoutId: number): Promise<MerchantPayout> {
  const payout = await payram.payouts.getPayoutById(payoutId);
  console.log('Payout status:', {
    id: payout.id,
    status: payout.status,
    transactionHash: payout.transactionHash,
    amount: payout.amount,
  });
  return payout;
}

Address Validation

地址验证

Always validate recipient addresses before creating payouts:
typescript
function validateAddress(address: string, blockchainCode: string): boolean {
  const patterns: Record<string, RegExp> = {
    ETH: /^0x[a-fA-F0-9]{40}$/,
    BTC: /^(?:[13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$/,
    MATIC: /^0x[a-fA-F0-9]{40}$/,
  };
  const pattern = patterns[blockchainCode];
  return pattern ? pattern.test(address) : false;
}
创建付款前请务必验证收款地址：
typescript
function validateAddress(address: string, blockchainCode: string): boolean {
  const patterns: Record<string, RegExp> = {
    ETH: /^0x[a-fA-F0-9]{40}$/,
    BTC: /^(?:[13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$/,
    MATIC: /^0x[a-fA-F0-9]{40}$/,
  };
  const pattern = patterns[blockchainCode];
  return pattern ? pattern.test(address) : false;
}

Database Schema for Payouts

付款数据库表结构

sql
CREATE TABLE payouts (
    id SERIAL PRIMARY KEY,
    payram_payout_id INTEGER UNIQUE NOT NULL,
    customer_id VARCHAR(255) NOT NULL,
    blockchain_code VARCHAR(50) NOT NULL,
    currency_code VARCHAR(50) NOT NULL,
    amount DECIMAL(20, 8) NOT NULL,
    to_address VARCHAR(255) NOT NULL,
    status VARCHAR(50) NOT NULL,
    transaction_hash VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
sql
CREATE TABLE payouts (
    id SERIAL PRIMARY KEY,
    payram_payout_id INTEGER UNIQUE NOT NULL,
    customer_id VARCHAR(255) NOT NULL,
    blockchain_code VARCHAR(50) NOT NULL,
    currency_code VARCHAR(50) NOT NULL,
    amount DECIMAL(20, 8) NOT NULL,
    to_address VARCHAR(255) NOT NULL,
    status VARCHAR(50) NOT NULL,
    transaction_hash VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

Framework Examples

框架示例

Express.js Route:
typescript
router.post('/api/payouts/payram', async (req, res) => {
  const payload = req.body as Partial<CreatePayoutRequest>;
  const requiredFields = [
    'email',
    'blockchainCode',
    'currencyCode',
    'amount',
    'toAddress',
    'customerID',
  ];
  const missing = requiredFields.filter((f) => !payload[f as keyof CreatePayoutRequest]);
  if (missing.length > 0) {
    return res.status(400).json({ error: 'MISSING_REQUIRED_FIELDS', missing });
  }

  try {
    const payout = await payram.payouts.createPayout(payload as CreatePayoutRequest);
    return res.status(201).json({
      id: payout.id,
      status: payout.status,
      amount: payout.amount,
    });
  } catch (error) {
    if (isPayramSDKError(error)) {
      console.error('Payram Error:', { status: error.status, requestId: error.requestId });
    }
    return res.status(502).json({ error: 'PAYRAM_CREATE_PAYOUT_FAILED' });
  }
});
Express.js 路由：
typescript
router.post('/api/payouts/payram', async (req, res) => {
  const payload = req.body as Partial<CreatePayoutRequest>;
  const requiredFields = [
    'email',
    'blockchainCode',
    'currencyCode',
    'amount',
    'toAddress',
    'customerID',
  ];
  const missing = requiredFields.filter((f) => !payload[f as keyof CreatePayoutRequest]);
  if (missing.length > 0) {
    return res.status(400).json({ error: 'MISSING_REQUIRED_FIELDS', missing });
  }

  try {
    const payout = await payram.payouts.createPayout(payload as CreatePayoutRequest);
    return res.status(201).json({
      id: payout.id,
      status: payout.status,
      amount: payout.amount,
    });
  } catch (error) {
    if (isPayramSDKError(error)) {
      console.error('Payram Error:', { status: error.status, requestId: error.requestId });
    }
    return res.status(502).json({ error: 'PAYRAM_CREATE_PAYOUT_FAILED' });
  }
});

Supported Payout Chains

支持的付款区块链

Same chains as deposits: Ethereum, Base, Polygon, Tron, Bitcoin.
Recommendation: Use Polygon or Tron for high-volume, low-value payouts (lowest fees).
与入金支持的区块链相同：Ethereum、Base、Polygon、Tron、Bitcoin。
推荐：对于高交易量、低价值的付款，使用Polygon或Tron（手续费最低）。

MCP Server Tools

MCP Server 工具

ToolPurpose
generate_payout_sdk_snippet
Payout creation code
generate_payout_status_snippet
Status polling code
工具用途
generate_payout_sdk_snippet
生成付款创建代码片段
generate_payout_status_snippet
生成状态查询代码片段

Referral Program

推荐计划

PayRam includes native referral tracking and reward automation.
PayRam内置原生推荐追踪与奖励自动化功能。

Setting Up Referrals

搭建推荐计划

  1. Dashboard: Settings → Referrals → Enable
  2. Configure: Set reward percentage or fixed amount
  3. Generate Links: Each user gets unique referral link
  4. Track: Dashboard shows clicks, signups, conversions
  1. 控制台：设置 → 推荐计划 → 启用
  2. 配置：设置奖励比例或固定金额
  3. 生成链接：每个用户可获取唯一推荐链接
  4. 追踪：控制台展示点击量、注册量、转化量

Referral API Integration

推荐计划API集成

Generate Referral Link:
javascript
const referralLink = await payram.createReferralLink({
  userId: 'affiliate_123',
  campaign: 'summer_promo',
});
// Returns: https://your-domain.com/ref/abc123
Validate Referral on Signup:
javascript
const validation = await payram.validateReferral({
  referralCode: 'abc123',
  newUserId: 'new_user_456',
});
Check Referral Status:
javascript
const stats = await payram.getReferralStats({
  userId: 'affiliate_123',
});
// Returns: { referrals: 45, earnings: 230, pending: 50 }
生成推荐链接：
javascript
const referralLink = await payram.createReferralLink({
  userId: 'affiliate_123',
  campaign: 'summer_promo',
});
// 返回：https://your-domain.com/ref/abc123
注册时验证推荐码：
javascript
const validation = await payram.validateReferral({
  referralCode: 'abc123',
  newUserId: 'new_user_456',
});
查看推荐状态：
javascript
const stats = await payram.getReferralStats({
  userId: 'affiliate_123',
});
// 返回：{ referrals: 45, earnings: 230, pending: 50 }

MCP Server Tools

MCP Server 工具

ToolPurpose
generate_referral_sdk_snippet
Referral link creation
generate_referral_validation_snippet
Signup attribution
generate_referral_status_snippet
Stats retrieval
generate_referral_route_snippet
Express/Next.js routes
工具用途
generate_referral_sdk_snippet
生成推荐链接创建代码片段
generate_referral_validation_snippet
生成注册归因验证代码片段
generate_referral_status_snippet
生成统计数据查询代码片段
generate_referral_route_snippet
生成Express/Next.js路由代码片段

Automated Reward Payouts

自动奖励付款

  1. Referrer's friend makes deposit
  2. PayRam calculates commission (e.g., 10% of deposit)
  3. Reward credited to referrer's balance
  4. Auto-payout when threshold reached (or manual trigger)
  1. 推荐人的好友完成入金
  2. PayRam计算佣金（如入金金额的10%）
  3. 奖励计入推荐人的余额
  4. 达到阈值时自动付款（或手动触发）

Troubleshooting

故障排除

"Insufficient balance" (400)

"余额不足" (400)

Check merchant balance, deposit funds, account for gas fees.
检查商家账户余额，存入资金，同时考虑Gas费用。

"Invalid address format" (400)

"地址格式无效" (400)

ETH/Polygon: 
0x
+ 40 hex chars. BTC: starts with 
1
/
3
(legacy) or 
bc1
(Bech32), 26-62 chars.
ETH/Polygon：需为
0x
开头加40位十六进制字符。BTC：以
1
/
3
开头（传统格式）或
bc1
开头（Bech32格式），长度为26-62位字符。

Amount must be string

金额必须为字符串

typescript
amount: '125.50'; // ✅ Correct
amount: 125.5; // ❌ Wrong - validation error
typescript
amount: '125.50'; // ✅ 正确
amount: 125.5; // ❌ 错误 - 验证不通过

Payout stuck in "pending-approval"

付款卡在"pending-approval"状态

Exceeds auto-approval threshold. Wait for admin approval or adjust thresholds.
金额超过自动审批阈值。等待管理员审批或调整阈值。

"Invalid mobile number format" (400)

"手机号格式无效" (400)

Use E.164 format: 
+15555555555
(no spaces, dashes, or parentheses).
需使用E.164格式：
+15555555555
（不能包含空格、短横线或括号）。

Environment Variables

环境变量

bash
PAYRAM_BASE_URL=https://your-payram-server:8080
PAYRAM_API_KEY=your-api-key
bash
PAYRAM_BASE_URL=https://your-payram-server:8080
PAYRAM_API_KEY=your-api-key

All PayRam Skills

所有PayRam技能

SkillWhat 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
需要帮助？请在Telegram上联系PayRam团队：@PayRamChat