Skip to content
RugWard
RugWard 文档
🌐 简体中文 ▾
☰ 菜单

RugWard Pay

REST API 参考

RugWard Pay 的全部商户端点，含请求与响应示例、API 密钥认证、错误、限制，以及 curl、Node.js、Python 和 PHP 代码。

本页内容

基础#

基础 URLhttps://rugward.com
格式请求和响应均为 JSON。每个请求体都要带 Content-Type: application/json（否则返回 415）。请求体限制在几 KB 以内。
认证在 Authorization: Bearer rwp_… 或 x-api-key: rwp_… 中提供 API 密钥
金额美元以字符串表示，最多 2 位小数（"25"、"25.50"）；币种金额为十进制字符串
时间Unix 毫秒（createdAt、expiresAt、paidAt）
错误{"error": "human readable message"}，有时带有 "retry": true

仅限服务器到服务器调用。 请把 API 密钥保存在你的服务器上。浏览器无法携带密钥调用商户 API（不允许跨域请求），而且放在网页中的密钥就等于公开了。

API 密钥#

在后台的 API keys 下创建密钥（需要登录）。密钥格式为 rwp_ 加 40 个字母和数字，且只显示一次：请立即复制到服务器的密钥存储中。RugWard 只保存 SHA-256 哈希，因此丢失的密钥无法再次显示：请新建一个并吊销旧的。每个商户最多 10 个密钥；后台会显示每个密钥的前缀及最近使用时间。

后台中的 API 密钥和 Webhook
创建或吊销 API 密钥，并设置 Webhook

密钥能做和不能做的事：

密钥可以密钥不能
创建、列出、读取和取消账单更改设置或收款地址
创建、列出和停用收款链接创建、列出或吊销 API 密钥
更改或读取 Webhook 及其密钥
创建测试账单

因此，泄露的密钥无法把你的资金转走：收款地址只能通过用钱包登录来更改。

端点#

方法和路径认证用途
POST /api/pay/merchant/invoices密钥或会话创建账单
GET /api/pay/merchant/invoices密钥或会话列出账单，最新的在前，每页 50 条
GET /api/pay/merchant/invoices/:id密钥或会话读取一张账单及其报价和付款（同时重新检查链上数据）
POST /api/pay/merchant/invoices/:id/cancel密钥或会话取消一张没有付款的未完成账单
GET /api/pay/merchant/links密钥或会话列出收款链接
POST /api/pay/merchant/links密钥或会话创建或停用收款链接
GET /api/pay/proof/:id公开付款证明（仅限 paid 或 overpaid 账单）

设置、API 密钥、Webhook 和无法匹配的付款都在后台管理（仅限钱包会话）。

创建账单#

POST /api/pay/merchant/invoices

字段类型必填规则
amountUsd字符串或数字是1 至 50000，最多 2 位小数
orderId字符串否1–64 个字符：字母、数字、. _ - : # /
description字符串否最多 200 个字符，向买家显示
redirectUrl字符串否https:// 网址（最多 500 个字符），付款后显示
expiresMin整数否15 至 10080（7 天）；默认 60
curl · create an invoice
curl -X POST https://rugward.com/api/pay/merchant/invoices \
  -H "Authorization: Bearer $RUGWARD_PAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsd": "25.00",
    "orderId": "1234",
    "description": "1 x T-shirt, size M",
    "redirectUrl": "https://shop.example/thanks?order=1234",
    "expiresMin": 60
  }'
201 Created
{
  "id": "Zx3kQ8pL2mN7vR1tY5wB9c",
  "url": "https://rugward.com/pay/i/Zx3kQ8pL2mN7vR1tY5wB9c",
  "status": "open",
  "expiresAt": 1793326882069,
  "assets": ["BTC", "ETH-8453", "USDC-8453", "USDT-56", "SOL", "USDC-SOL"]
}

把买家引导到 url。assets 列出买家可选择的资产 id（即你已启用且有收款地址的币种）。

同一请求的其他语言版本：

Node.js 18+ (server side only)
// Never put the API key in a browser page: call RugWard Pay from your server.
const res = await fetch("https://rugward.com/api/pay/merchant/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RUGWARD_PAY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amountUsd: "25.00", orderId: "1234", expiresMin: 60 }),
});
const body = await res.json();
if (!res.ok) throw new Error(body.error);
// Save body.id with your order, then send the buyer to body.url
console.log(body.id, body.url);
Python 3 (requests)
import os, requests

r = requests.post(
    "https://rugward.com/api/pay/merchant/invoices",
    headers={"Authorization": f"Bearer {os.environ['RUGWARD_PAY_KEY']}"},
    json={"amountUsd": "25.00", "orderId": "1234", "expiresMin": 60},
    timeout=15,
)
data = r.json()
if r.status_code != 201:
    raise RuntimeError(data.get("error"))
print(data["id"], data["url"])  # store the id, redirect the buyer to the url
PHP 8 (cURL)
<?php
$ch = curl_init("https://rugward.com/api/pay/merchant/invoices");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("RUGWARD_PAY_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["amountUsd" => "25.00", "orderId" => "1234", "expiresMin" => 60]),
]);
$data = json_decode(curl_exec($ch), true);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($code !== 201) { throw new Exception($data["error"] ?? "RugWard Pay error"); }
header("Location: " . $data["url"]); // send the buyer to the hosted checkout

读取账单#

GET /api/pay/merchant/invoices/:id。读取账单时也会检查各区块链上是否有新付款，因此这是发货前确认付款的正确调用（配合 Webhook 使用）。

curl · read one invoice
curl https://rugward.com/api/pay/merchant/invoices/Zx3kQ8pL2mN7vR1tY5wB9c \
  -H "Authorization: Bearer $RUGWARD_PAY_KEY"
200 OK
{
  "invoice": {
    "id": "Zx3kQ8pL2mN7vR1tY5wB9c",
    "status": "paid",
    "amountUsd": "25.00",
    "orderId": "1234",
    "description": "1 x T-shirt, size M",
    "redirectUrl": "https://shop.example/thanks?order=1234",
    "createdAt": 1793323282069,
    "expiresAt": 1793326882069,
    "paidAt": 1793324100512,
    "assets": ["BTC", "ETH-8453", "USDC-8453", "USDT-56", "SOL", "USDC-SOL"],
    "test": false,
    "quotes": [
      {
        "id": 4711,
        "asset": "USDC-8453",
        "amount": "25.000629",
        "rateUsd": "1",
        "address": "0xYourMerchantAddress…",
        "expiresAt": 1793325082069
      }
    ],
    "payments": [
      {
        "txid": "0x…",
        "asset": "USDC-8453",
        "amount": "24.875626",
        "confirmations": 30,
        "required": 30,
        "confirmed": true,
        "seenAt": 1793324012000,
        "explorer": "https://basescan.org/tx/0x…"
      }
    ]
  }
}
  • quotes：买家选择的每个币种各一条（金额、汇率、收款地址、汇率锁定到期时间）。
  • payments：该账单下看到的每笔交易，包括 confirmations、所需的 required 数量和 confirmed。
  • 对于 Base 分账合约付款，amount 是实际到达你账户的金额（99.5%）。

列出账单#

GET /api/pay/merchant/invoices?before=<createdAt>：每页 50 条，最新的在前。要获取下一页，请传入你收到的最后一张账单的 createdAt。

curl · list invoices (50 per page, newest first)
curl "https://rugward.com/api/pay/merchant/invoices" \
  -H "Authorization: Bearer $RUGWARD_PAY_KEY"

# next page: pass the createdAt of the last invoice you received
curl "https://rugward.com/api/pay/merchant/invoices?before=1793323282069" \
  -H "Authorization: Bearer $RUGWARD_PAY_KEY"
200 OK
{
  "invoices": [
    {
      "id": "Zx3kQ8pL2mN7vR1tY5wB9c",
      "status": "open",
      "amountUsd": "25.00",
      "orderId": "1234",
      "description": "1 x T-shirt, size M",
      "createdAt": 1793323282069,
      "expiresAt": 1793326882069,
      "paidAt": null
    }
  ]
}

取消账单#

POST /api/pay/merchant/invoices/:id/cancel（无请求体）。仅当账单为 open 且未看到任何付款时有效；否则返回 409。

curl · cancel an open invoice
curl -X POST https://rugward.com/api/pay/merchant/invoices/Zx3kQ8pL2mN7vR1tY5wB9c/cancel \
  -H "Authorization: Bearer $RUGWARD_PAY_KEY"

# 200 {"ok":true}
# 409 {"error":"Only your open invoices without payments can be canceled."}

收款链接#

使用 {amountUsd, description?, redirectUrl?} 调用 POST /api/pay/merchant/links 可创建可重复使用的链接；{"deactivate": "<link id>"} 可停用链接。GET 最多列出 100 个链接，包含 uses、active 和 createdAt。必须先接受商户条款。参见收款链接。

curl · create a reusable payment link
curl -X POST https://rugward.com/api/pay/merchant/links \
  -H "Authorization: Bearer $RUGWARD_PAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountUsd": "15", "description": "Monthly membership", "redirectUrl": "https://shop.example/welcome"}'

# 201 {"id":"k33JZ0ij5F2yLDprwrQgjN","url":"https://rugward.com/pay/l/k33JZ0ij5F2yLDprwrQgjN"}

# list your links
curl https://rugward.com/api/pay/merchant/links -H "Authorization: Bearer $RUGWARD_PAY_KEY"

# turn one off
curl -X POST https://rugward.com/api/pay/merchant/links \
  -H "Authorization: Bearer $RUGWARD_PAY_KEY" -H "Content-Type: application/json" \
  -d '{"deactivate": "k33JZ0ij5F2yLDprwrQgjN"}'

错误#

Error response (any 4xx/5xx)
{ "error": "Amount in USD, e.g. 25 or 25.50." }

// some temporary errors also carry  "retry": true
HTTP含义处理方式
400输入无效（消息会说明是哪个字段）修正请求
401缺少 API 密钥或密钥无效检查密钥；它可能已被吊销
403跨站请求被拒绝、未接受商户条款、账户已暂停，或该操作不允许使用密钥阅读错误消息
404未找到或不属于你检查 id
409冲突（例如取消已支付的账单，或已有 100 个有效链接）阅读错误消息
415请求体不是 JSON发送 Content-Type: application/json
429触发频率限制，或过去一小时已创建 500 张账单等待后以退避方式重试
451你所在地区不可用—
带 "retry": true 的 503某个区块链或价格来源暂时无法访问几秒后重试

限制#

  • 请求频率： 所有 /api/pay/* 端点合计每个 IP 地址每分钟约 20 次请求，另外每个端点组每分钟上限 30 次。请使用 Webhook 而不是轮询；如果一定要轮询，每张未完成账单每分钟一次已经足够。
  • 账单： 每个商户每小时 500 张。
  • 收款链接： 每个商户最多 100 个有效链接；每个链接每小时最多创建 100 张账单。

集成检查清单#

  1. 在顾客结账时从你的服务器创建账单；将 id 与订单一起保存。
  2. 将顾客重定向到 url。
  3. 收到 invoice.paid 或 invoice.overpaid（Webhook）时，验证签名，然后用 GET /api/pay/merchant/invoices/:id 重新读取账单，在发货前检查 status 和 amountUsd。
  4. 处理 underpaid、late 和 expired（参见状态）。
  5. 让你的处理程序具备幂等性：同一事件可能会到达不止一次。

最后更新: 2026年10月30日

REST API 参考 · RugWard 文档 | RugWard