商户管理 API

商户管理 API 提供账户信息查询、API 密钥管理、系统设置配置等功能，帮助商户全面管理其 Payve 账户。

概述

基础 URL

https://api.payve.io/api/v1

认证方式

Bearer Token (JWT)

所需权限

merchant:read, merchant:write

速率限制

100 请求/分钟

商户信息

获取商户信息

获取当前商户的详细信息。

GET/merchant/profile

响应示例

{
  "merchantId": "mer_xGh8Kl9mNpQr",
  "email": "admin@merchant.com",
  "companyName": "Example Company Ltd.",
  "website": "https://example.com",
  "country": "CN",
  "timezone": "Asia/Shanghai",
  "status": "active",
  "kycLevel": 0,
  "createdAt": "2024-01-01T00:00:00Z",
  "settings": {
    "language": "zh",
    "currency": "USD",
    "notificationEmail": "notify@merchant.com",
    "twoFactorEnabled": false,
    "ipWhitelist": []
  },
  "statistics": {
    "totalTransactions": 1520,
    "totalVolume": "250000.00",
    "successRate": "98.5%",
    "averageTransactionValue": "164.47"
  }
}

JSON

代码已折叠

共 24 行

更新商户信息

更新商户的基本信息。

PATCH/merchant/profile

请求参数

参数	类型	必填	说明
`companyName`	string	❌	公司名称
`website`	string	❌	公司网站
`notificationEmail`	string	❌	通知邮箱
`timezone`	string	❌	时区设置
`language`	string	❌	界面语言（zh, en）

请求示例

{
  "companyName": "New Company Name Ltd.",
  "website": "https://newwebsite.com",
  "notificationEmail": "new-notify@merchant.com",
  "timezone": "Asia/Hong_Kong",
  "language": "en"
}

API 密钥管理

获取 API 密钥列表

GET/merchant/api-keys

响应示例

{
  "apiKeys": [
    {
      "id": "key_abc123",
      "name": "生产环境密钥",
      "key": "pk_live_xGh8Kl9m...",
      "permissions": ["payments:read", "payments:write", "webhooks:write"],
      "status": "active",
      "lastUsedAt": "2024-01-15T10:00:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "expiresAt": null,
      "ipWhitelist": ["192.168.1.1", "10.0.0.0/24"]
    },
    {
      "id": "key_def456",
      "name": "测试环境密钥",
      "key": "pk_test_yHi9Lm0n...",
      "permissions": ["payments:read"],
      "status": "active",
      "lastUsedAt": "2024-01-14T15:30:00Z",
      "createdAt": "2024-01-05T00:00:00Z",
      "expiresAt": "2024-12-31T23:59:59Z",
      "ipWhitelist": []
    }
  ],
  "total": 2
}

JSON

代码已折叠

共 27 行

创建 API 密钥

创建新的 API 密钥，用于程序化访问。

POST/merchant/api-keys

请求参数

参数	类型	必填	说明
`name`	string	✅	密钥名称
`permissions`	array	✅	权限列表
`expiresIn`	integer	❌	过期时间（秒）
`ipWhitelist`	array	❌	IP 白名单

权限列表

权限	说明
`payments:read`	查询支付订单
`payments:write`	创建支付订单
`payments:cancel`	取消支付订单
`wallet:read`	查询钱包余额
`wallet:write`	发起提现操作
`webhooks:read`	查询 Webhook 配置
`webhooks:write`	修改 Webhook 配置
`merchant:read`	查询商户信息
`merchant:write`	修改商户信息
`reports:read`	查看报表数据

请求示例

{
  "name": "移动应用密钥",
  "permissions": [
    "payments:read",
    "payments:write"
  ],
  "expiresIn": 31536000,
  "ipWhitelist": []
}

响应示例

{
  "id": "key_ghi789",
  "name": "移动应用密钥",
  "key": "pk_live_zAb2Cd3e...",
  "secret": "sk_live_fGh4Ij5k...",
  "permissions": ["payments:read", "payments:write"],
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T10:30:00Z"
}

重要：密钥的 secret 只会在创建时显示一次，请妥善保存。如果丢失，需要重新创建密钥。

更新 API 密钥

更新现有 API 密钥的设置。

PATCH/merchant/api-keys/{keyId}

{
  "name": "更新后的名称",
  "permissions": ["payments:read", "wallet:read"],
  "ipWhitelist": ["192.168.1.0/24"],
  "status": "active"
}

撤销 API 密钥

撤销（删除）API 密钥，立即生效。

DELETE/merchant/api-keys/{keyId}

{
  "confirmDelete": true,
  "reason": "密钥泄露"
}

安全设置

双因素认证（2FA）

启用 2FA

POST/merchant/security/2fa/enable

{
  "type": "totp",
  "verificationCode": "123456"
}

响应包含 QR 码用于扫描：

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,...",
  "backupCodes": [
    "ABC123",
    "DEF456",
    "GHI789"
  ]
}

禁用 2FA

POST/merchant/security/2fa/disable

{
  "verificationCode": "123456",
  "password": "currentPassword"
}

IP 白名单

设置 IP 白名单

限制只有特定 IP 地址可以访问 API。

POST/merchant/security/ip-whitelist

{
  "enabled": true,
  "addresses": [
    "192.168.1.1",
    "10.0.0.0/24",
    "2001:db8::/32"
  ],
  "verificationCode": "123456"
}

登录日志

查询登录历史

GET/merchant/security/login-history

{
  "logins": [
    {
      "id": "login_abc123",
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0...",
      "location": "Shanghai, China",
      "status": "success",
      "loginAt": "2024-01-15T10:00:00Z",
      "device": "Chrome on Windows"
    },
    {
      "id": "login_def456",
      "ipAddress": "192.168.1.101",
      "userAgent": "Mozilla/5.0...",
      "location": "Beijing, China",
      "status": "failed",
      "failReason": "invalid_password",
      "loginAt": "2024-01-15T09:00:00Z",
      "device": "Safari on macOS"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

JSON

代码已折叠

共 28 行

通知设置

配置通知偏好

设置接收哪些类型的通知。

POST/merchant/notifications/preferences

{
  "email": {
    "enabled": true,
    "address": "notify@merchant.com",
    "events": [
      "payment.succeeded",
      "payment.failed",
      "withdrawal.completed",
      "security.login"
    ]
  },
  "sms": {
    "enabled": false,
    "phone": "+861234567890",
    "events": []
  },
  "webhook": {
    "enabled": true,
    "url": "https://merchant.com/notifications",
    "events": ["payment.succeeded"]
  }
}

JSON

代码已折叠

共 22 行

通知事件类型

事件类型	说明
`payment.succeeded`	支付成功
`payment.failed`	支付失败
`payment.expired`	支付过期
`withdrawal.completed`	提现完成
`withdrawal.failed`	提现失败
`security.login`	新登录
`security.api_key_created`	API 密钥创建
`security.settings_changed`	安全设置更改
`account.kyc_updated`	KYC 状态更新
`account.limit_reached`	达到限额

报表和统计

获取交易统计

GET/merchant/statistics

查询参数

参数	类型	说明
`period`	string	统计周期（today, week, month, year）
`startDate`	string	开始日期
`endDate`	string	结束日期
`currency`	string	币种筛选

响应示例

{
  "period": "month",
  "summary": {
    "totalTransactions": 450,
    "successfulTransactions": 441,
    "failedTransactions": 9,
    "totalVolume": "45000.00",
    "totalFees": "450.00",
    "averageTransactionValue": "100.00",
    "successRate": "98%"
  },
  "byDay": [
    {
      "date": "2024-01-15",
      "transactions": 15,
      "volume": "1500.00",
      "fees": "15.00"
    }
  ],
  "byCurrency": [
    {
      "currency": "USDT",
      "transactions": 300,
      "volume": "30000.00",
      "percentage": "66.67%"
    },
    {
      "currency": "BTC",
      "transactions": 150,
      "volume": "15000.00",
      "percentage": "33.33%"
    }
  ],
  "byNetwork": [
    {
      "network": "TRON",
      "transactions": 250,
      "volume": "25000.00"
    },
    {
      "network": "Ethereum",
      "transactions": 200,
      "volume": "20000.00"
    }
  ]
}

JSON

代码已折叠

共 46 行

导出报表

生成并下载详细报表。

POST/merchant/reports/export

{
  "type": "transactions",
  "format": "csv",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "filters": {
    "status": "completed",
    "currency": "USDT"
  }
}

响应返回下载链接：

{
  "reportId": "rpt_abc123",
  "status": "processing",
  "downloadUrl": null,
  "estimatedTime": 30
}

查询报表状态：

GET/merchant/reports/{reportId}

{
  "reportId": "rpt_abc123",
  "status": "completed",
  "downloadUrl": "https://api.payve.io/downloads/rpt_abc123.csv",
  "expiresAt": "2024-01-16T10:30:00Z",
  "size": "1.2MB"
}

账户限额

查询账户限额

GET/merchant/limits

{
  "kycLevel": 0,
  "limits": {
    "daily": {
      "transaction": {
        "limit": "10000.00",
        "used": "5000.00",
        "remaining": "5000.00"
      },
      "withdrawal": {
        "limit": "5000.00",
        "used": "1000.00",
        "remaining": "4000.00"
      }
    },
    "monthly": {
      "transaction": {
        "limit": "100000.00",
        "used": "45000.00",
        "remaining": "55000.00"
      },
      "withdrawal": {
        "limit": "50000.00",
        "used": "10000.00",
        "remaining": "40000.00"
      }
    },
    "singleTransaction": {
      "minimum": "1.00",
      "maximum": "5000.00"
    }
  },
  "nextLevel": {
    "level": 1,
    "requirements": "完成 KYC 认证",
    "benefits": {
      "dailyTransactionLimit": "50000.00",
      "monthlyTransactionLimit": "500000.00",
      "feeDiscount": "10%"
    }
  }
}

JSON

代码已折叠

共 42 行

KYC 认证

提交 KYC 申请

POST/merchant/kyc/submit

{
  "type": "business",
  "businessInfo": {
    "legalName": "Example Company Ltd.",
    "registrationNumber": "123456789",
    "country": "CN",
    "address": "123 Business Street, Shanghai"
  },
  "documents": [
    {
      "type": "business_license",
      "fileId": "file_abc123"
    },
    {
      "type": "bank_statement",
      "fileId": "file_def456"
    }
  ],
  "contactPerson": {
    "name": "张三",
    "position": "CEO",
    "email": "ceo@example.com",
    "phone": "+861234567890"
  }
}

JSON

代码已折叠

共 25 行

查询 KYC 状态

GET/merchant/kyc/status

{
  "kycLevel": 0,
  "status": "pending",
  "submittedAt": "2024-01-15T10:00:00Z",
  "reviewedAt": null,
  "rejectionReason": null,
  "documents": [
    {
      "type": "business_license",
      "status": "reviewing"
    },
    {
      "type": "bank_statement",
      "status": "approved"
    }
  ],
  "nextSteps": "等待审核完成，预计 1-3 个工作日"
}

JSON

代码已折叠

共 18 行

费率查询

获取当前费率

GET/merchant/fees

{
  "standardFees": {
    "transaction": "1.0%",
    "withdrawal": "1.0%",
    "minimumFee": "0.10 USD"
  },
  "customFees": null,
  "volumeDiscounts": [
    {
      "monthlyVolume": "10000.00",
      "discount": "0%"
    },
    {
      "monthlyVolume": "50000.00",
      "discount": "5%"
    },
    {
      "monthlyVolume": "100000.00",
      "discount": "10%"
    },
    {
      "monthlyVolume": "500000.00",
      "discount": "15%"
    }
  ],
  "currentVolume": "45000.00",
  "currentDiscount": "0%",
  "effectiveFee": "1.0%"
}

JSON

代码已折叠

共 29 行

示例代码

完整的商户设置流程

const PayveAPI = require('@payve/sdk');
 
async function setupMerchant() {
  const api = new PayveAPI({
    apiKey: process.env.PAYVE_API_KEY,
    apiSecret: process.env.PAYVE_API_SECRET
  });
  
  try {
    // 1. 获取商户信息
    const profile = await api.merchant.getProfile();
    console.log('Merchant:', profile.companyName);
    
    // 2. 创建 API 密钥
    const apiKey = await api.merchant.createApiKey({
      name: '生产环境密钥',
      permissions: [
        'payments:read',
        'payments:write',
        'wallet:read'
      ],
      expiresIn: 365 * 24 * 60 * 60 // 1年
    });
    console.log('API Key created:', apiKey.key);
    // 保存 secret！
    saveToSecureStorage(apiKey.secret);
    
    // 3. 配置 Webhook
    await api.webhooks.configure({
      url: 'https://api.merchant.com/webhook',
      events: ['payment.succeeded', 'payment.failed'],
      active: true
    });
    
    // 4. 设置通知偏好
    await api.merchant.setNotifications({
      email: {
        enabled: true,
        address: 'notify@merchant.com',
        events: ['payment.succeeded', 'withdrawal.completed']
      }
    });
    
    // 5. 启用 2FA（可选但推荐）
    const twoFactor = await api.merchant.enable2FA({
      type: 'totp'
    });
    console.log('2FA QR Code:', twoFactor.qrCode);
    console.log('Backup codes:', twoFactor.backupCodes);
    
    // 6. 设置 IP 白名单（可选）
    await api.merchant.setIPWhitelist({
      enabled: true,
      addresses: ['203.0.113.0/24']
    });
    
    console.log('Merchant setup completed!');
  } catch (error) {
    console.error('Setup failed:', error);
  }
}

JAVASCRIPT

代码已折叠

共 61 行

监控和报表

async function generateMonthlyReport() {
  const api = new PayveAPI({
    apiKey: process.env.PAYVE_API_KEY,
    apiSecret: process.env.PAYVE_API_SECRET
  });
  
  // 获取统计数据
  const stats = await api.merchant.getStatistics({
    period: 'month',
    startDate: '2024-01-01',
    endDate: '2024-01-31'
  });
  
  console.log('Monthly Summary:');
  console.log(`- Total transactions: ${stats.summary.totalTransactions}`);
  console.log(`- Success rate: ${stats.summary.successRate}`);
  console.log(`- Total volume: ${stats.summary.totalVolume}`);
  console.log(`- Total fees: ${stats.summary.totalFees}`);
  
  // 生成详细报表
  const report = await api.merchant.exportReport({
    type: 'transactions',
    format: 'csv',
    startDate: '2024-01-01',
    endDate: '2024-01-31'
  });
  
  // 等待报表生成
  let reportStatus = 'processing';
  while (reportStatus === 'processing') {
    await sleep(5000);
    const status = await api.merchant.getReport(report.reportId);
    reportStatus = status.status;
    
    if (reportStatus === 'completed') {
      console.log('Report ready:', status.downloadUrl);
      // 下载报表
      await downloadFile(status.downloadUrl, 'monthly-report.csv');
    }
  }
}

JAVASCRIPT

代码已折叠

共 41 行

最佳实践

1. API 密钥安全

使用环境变量存储密钥
定期轮换密钥
为不同环境使用不同密钥
设置最小必要权限

2. 账户安全

启用双因素认证
设置 IP 白名单
定期检查登录日志
及时更新通知邮箱

3. 监控和告警

// 设置关键指标监控
async function monitorAccount() {
  const api = new PayveAPI();
  
  // 检查限额使用情况
  const limits = await api.merchant.getLimits();
  if (limits.daily.transaction.remaining < 1000) {
    sendAlert('Daily transaction limit nearly reached');
  }
  
  // 检查异常登录
  const logins = await api.merchant.getLoginHistory();
  const suspiciousLogins = logins.filter(l => 
    l.status === 'failed' || 
    isUnknownLocation(l.location)
  );
  
  if (suspiciousLogins.length > 0) {
    sendAlert('Suspicious login attempts detected');
  }
  
  // 检查 API 密钥使用
  const apiKeys = await api.merchant.getApiKeys();
  const unusedKeys = apiKeys.filter(k => 
    Date.now() - new Date(k.lastUsedAt) > 30 * 24 * 60 * 60 * 1000
  );
  
  if (unusedKeys.length > 0) {
    console.log('Consider revoking unused API keys');
  }
}

JAVASCRIPT

代码已折叠

共 31 行

概述

商户信息

获取商户信息

响应示例

更新商户信息

请求参数

请求示例

API 密钥管理

获取 API 密钥列表

响应示例

创建 API 密钥

请求参数

权限列表

请求示例

响应示例

更新 API 密钥

撤销 API 密钥

安全设置

双因素认证（2FA）

启用 2FA

禁用 2FA

IP 白名单

设置 IP 白名单

登录日志

查询登录历史

通知设置

配置通知偏好

通知事件类型

报表和统计

获取交易统计

查询参数

响应示例

导出报表

账户限额

查询账户限额

KYC 认证

提交 KYC 申请

查询 KYC 状态

费率查询

获取当前费率

示例代码

完整的商户设置流程

监控和报表

最佳实践

1. API 密钥安全

2. 账户安全

3. 监控和告警

相关文档