商家入驻开放申请中立即申请 →

文档中心 / 商家上手指南

商家上手指南

从登录后台到收到第一笔付款。界面文字以后台实际显示为准，英文菜单名附在括号里。

本页内容
  1. 开始之前：准备清单
  2. 登录后台
  3. 确认区块链节点
  4. 设置充值钱包（主账户与冷钱包）
  5. 设置热钱包
  6. 创建测试支付链接
  7. 通过 API 创建支付
  8. 接收 Webhook 回调
  9. 退款与出款
  10. 安全清单

1. 开始之前：准备清单

  • 商家账号与登录地址。审核通过后，我们会把它们发给你。
  • 一个浏览器钱包（例如 MetaMask）。它将作为你的“主账户”，用来部署归集合约。
  • 每条要开通的链上，准备少量原生币。部署合约需要付一次 gas：Ethereum、Base 用 ETH，Polygon 用 POL。
  • 一个专门新建的热钱包。平台不提供热钱包，需要你自己准备（见第 5 节），并在每条链上放少量原生币，用来支付归集的 gas 和出款。
  • 一个你自己控制的冷钱包地址。所有收款最终会归集到这里，强烈建议使用硬件钱包。

任何时候都不要把私钥或助记词发给任何人，包括我们。我们不会索取。唯一需要你填入私钥的地方，是后台“添加热钱包”那一步，而且只能填一个专门新建、只放少量 gas 费的钱包（见第 5 节）。

2. 登录后台

使用开户邮件里的登录地址和凭证登录。请只通过我们发给你的地址登录，不要点击来源不明的链接。

首次登录后，请立即修改初始密码，并把凭证保存在密码管理器里。

3. 确认区块链节点

路径：设置 → 集成 → 节点配置（Settings → Integrations → Node Configurations）。

  • 每条链会显示节点数量、有多少在线，以及最近处理到的区块。系统预置了公共节点，测试和小流量时通常开箱即用。
  • 公共节点可能被限流。流水较大或需要不间断运行时，建议点击 添加节点（Add Node），填入 Alchemy、Infura 等服务商的节点地址。
  • 节点地址里通常带有密钥，请自己保管，不要公开。

4. 设置充值钱包（主账户与冷钱包）

先理解四个概念：

概念作用
主账户（Master account）你的浏览器钱包账户。每位客户看到的充值地址都由它派生，它也用来部署归集合约。
充值钱包（Deposit wallet）客户付款的地址。每笔订单或每位客户一个，都关联到同一个主账户。
冷钱包（Cold wallet）资金最终归集的地方，不直接暴露给客户。
归集合约（Sweep contract）每条链上部署一次，之后把充值地址里的资金自动转入冷钱包，不需要暴露私钥。

操作步骤

  1. 左侧菜单进入 钱包管理 → 充值钱包，点击 + 设置充值钱包（Set Up Deposit Wallet），选择网络。EVM 同时覆盖 Ethereum、Base 和 Polygon。
  2. 选择这个钱包所属的项目。已经配过的项目会显示“Wallet already present”，没配过的显示“Ready”。
  3. 给钱包起个名字，点击 连接钱包（Connect wallet），在浏览器钱包里授权。主账户会部署合约，为每位客户生成唯一的充值地址。
  4. 填入你的 冷钱包地址，点击 部署合约（Deploy contract），在钱包里确认这笔交易。
  5. 部署完成后，系统会生成一批尚未分配的充值地址。可以点 创建测试支付链接，用 1 美元验证整个流程。
  6. 每次部署只覆盖一条链。1/3 ready 表示三条 EVM 链里只有一条完成。其余的重复上面的步骤，每次连接同一个主钱包。

冷钱包地址请反复核对。资金会自动归集到这个地址，填错无法追回。建议对照硬件钱包屏幕上显示的地址逐位确认，并先只开通一条链，测试无误后再开通其余。

归集是怎么触发的？一个充值地址需要先达到一次性的最低余额（默认约相当于 5 美元），系统才会为它部署智能钱包合约；达不到则保持“休眠”，不会归集。之后按金额、地址数量或时间三种条件之一触发归集。这些阈值可以调整。

5. 设置热钱包

热钱包是 PayRam 唯一保存私钥的钱包，私钥加密后存放在服务器上。它只做三件事：支付归集所需的 gas、从该钱包发出出款、覆盖相关操作的链上费用。

  1. 左侧菜单进入 钱包管理 → 热钱包，点击 + 添加热钱包（Add Hot Wallet）。
  2. 选择链族：EVM（同时覆盖 Ethereum、Base、Polygon）或 Tron。一个链族一个热钱包。
  3. 填入该链上一个钱包的私钥并起名，保存。
  4. 在这个钱包所在行，点击项目数量旁边的编辑图标，选择哪些项目使用它。每个项目要为它接收的网络配置热钱包，没有共用的兜底。

只用一个专门新建的钱包。不要使用你的主账户或冷钱包的私钥。里面只放够付 gas 和近期出款的少量余额，并定期补充。这是整套系统里唯一的“私钥在服务器上”的钱包，而且这台服务器由平台运营。请把它当作运营用的零钱包，只放你愿意放在这里的金额。

热钱包由你自备，gas 也由你承担。平台不提供热钱包，也不代付 gas 或出款资金。新建钱包后，向它转入少量原生币（Ethereum、Base 用 ETH，Polygon 用 POL）。退款等出款也从这个钱包发出，所以还要放入相应的币。余额耗尽后，系统无法支付归集所需的 gas，也无法出款。建议在“设置”里开启邮件提醒，余额不足时能及时收到通知。

6. 创建测试支付链接

  1. 点击左侧菜单顶部的 创建支付链接（Create Payment Link）。
  2. 选择客户：在“按邮箱搜索会员”里输入。第一次使用时列表是空的，点击 添加会员（Add New Member），填客户邮箱、选择项目。
  3. 输入要收取的金额（美元），点击 生成支付链接。
  4. 可以复制链接发给客户，也可以点击“打开链接”看客户会看到什么：金额、折算的币种和一个充值地址。页面会持续监听到账，状态自动更新。

客户在“用加密货币支付”下选择币种和网络。达到所需的区块确认数后，页面显示支付完成。第一次请只用 1 美元做测试。

7. 通过 API 创建支付

基础地址（BASE_URL）在后台 设置 → 站点地址（Site URL）里查看。API 密钥请在后台生成并妥善保管，调用时放在请求头 API-Key 里。

创建支付

curl --location 'https://pay.payramhost.com/api/v1/payment' \
  --header 'API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customerEmail": "buyer@example.com",
    "customerID": "1001",
    "amountInUSD": 10,
    "invoiceID": "INV-0090"
  }'
字段必填说明
customerEmail是客户邮箱
customerID是客户在你系统里的唯一编号
amountInUSD是金额，美元
invoiceID否你自己的订单号，会在 Webhook 的 invoice_id 里原样返回，便于对账
expire否过期时间，RFC 3339 格式，默认 24 小时
currency否限定只能用某个币种，例如 USDC。不填则由客户选择
network否限定只能用某条链，例如 BASE，要和 currency 一起用

返回内容里的 url 就是发给客户的付款页面，reference_id 用于后续查询这笔支付：

{
  "host": "https://pay.payramhost.com",
  "reference_id": "c80f5363-0397-4761-aa1a-3155c3a21470",
  "url": "https://pay.payramhost.com/payments?reference_id=c80f5363-...&host=https://pay.payramhost.com"
}

查询支付状态等其他接口，请参考 PayRam 官方文档（英文）里的 Payments API 部分。

8. 接收 Webhook 回调

检测到付款并在链上推进时，系统会向你登记的地址发送 POST 请求，你不需要轮询。

  1. 后台进入 设置 → Webhook，点击 添加端点（Add Endpoint）。
  2. 填入你的 HTTPS 地址（必须能从公网访问）和一段说明，保存并设为启用。

校验签名（务必做）

请求头 X-Payram-Signature 的格式是 sha256=<hex>，用你的项目 API 密钥对原始请求体做 HMAC-SHA256。必须用收到的原始字节计算，不要把解析后的 JSON 再序列化一遍。

const crypto = require('crypto');

function verifyPayramSignature(rawBody, signatureHeader, apiKey) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', apiKey).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader || '');
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

重试与幂等

  • 你的服务器收到后要返回 2xx。返回 400 及以上或超过 60 秒无响应，都算失败并会重试。
  • 最终状态（已关闭或已取消）会先快速重试 3 次，之后按 30 分钟、1、2、4、8、24、48 小时长期重试；第七次长期重试之后标记为失败，不再发送。漏掉的请用状态查询接口对账。
  • 同一状态可能收到多次，请用 reference_id（或 invoice_id）加 status 去重。
  • 链上确认期间还会收到进度通知，带有 confirmation_current / confirmation_required（例如 3 / 12）。

状态值的含义见 术语对照表。

9. 退款与出款

  • 链上支付没有自动拒付，也没有自动退款。退款需要你在后台或通过 API 手动向客户的地址转回。
  • 出款从项目的热钱包发出。没有为该项目配置热钱包，就无法出款。
  • 客户少付时，支付保持“部分付款”状态，直到付清；多付时，多出的部分会在后台显示，由你决定如何处理。

10. 安全清单

  • 私钥、助记词只有你自己知道，不发给任何人。
  • 冷钱包用硬件钱包，地址每次修改都对照硬件屏幕核对。
  • 热钱包只放少量余额，只用专门新建的钱包。
  • API 密钥只放在你的服务器上，不要写进网页或手机 App 里。
  • 处理 Webhook 时一定校验签名，并按 reference_id 做幂等处理。
  • 只通过我们发给你的地址登录。收到“紧急修改钱包地址”之类的信息，先通过其他渠道向我们确认。