开发者

API 参考

一个用于账单、支付链接、余额和接受币种的小型 REST API。它通过 HTTPS 传输 JSON，每个请求都需使用您的密钥。

基础 URL

生产环境: https://cryptomerchant.online/api/v1
本地开发: http://localhost:3000/api/v1

此 API 的机器可读描述位于 /openapi.json（OpenAPI 3.1）。您可以将其导入 Postman 或客户端生成器。

身份验证

在每个请求的 Authorization 请求头中以 Bearer 令牌的形式发送您的密钥。在后台的开发者中创建密钥。

HTTP

Authorization: Bearer cm_live_…

主网上的密钥以 cm_live_ 开头，测试网上的密钥以 cm_test_ 开头。
完整密钥仅在创建时显示一次。我们只存储其哈希值，因此请妥善保存。
仅在您的服务器上使用密钥。切勿将其放入网页、移动应用或公开的代码仓库中。
如果密钥可能已泄露，请在后台将其撤销并创建新的密钥。

错误

请求失败时，响应会返回 HTTP 错误状态码，以及包含机器可读的 code 和人类可读的 message 的 JSON 正文：

JSON

{
  "error": {
    "code": "amount_too_small",
    "message": "Amount must be at least 0.50 USD."
  }
}

HTTP 状态码

400: 请求无效，例如缺少字段或金额过小。
401: API 密钥缺失、错误或已被撤销。
403: 您的账户无法执行此操作：账户尚未激活，或已被暂停。
404: 对象不存在，或属于其他商家。
409: 账单在当前状态下无法执行此操作，例如取消一张已有付款的账单。
500: 我们这边出了问题。请稍后重试。

可能出现的错误代码

invalid_json: 请求正文不是 JSON 对象。
invalid_request: 某个字段缺失或无效。错误信息会指明该字段。
unauthorized: API 密钥缺失、错误或已被撤销。
account_suspended: 此商户账户已被暂停。
merchant_not_live: 您的账户尚未激活。请先在后台完成设置。
invalid_amount: 金额缺失、不是数字或不大于零。
amount_too_small: 金额价值低于 0.50 美元。
invalid_asset: 该币种 ID 不是已知的币种。
asset_not_accepted: 您不接受该币种。
invalid_state: 账单在当前状态下无法执行此操作。
not_found: 不存在具有该 ID 的对象。
server_error: 我们这边出了问题。

账单对象

账单在 API 响应和 Webhook 中采用此结构。金额为十进制字符串，因此不会损失精度。

idstring: 账单 ID，以 inv_ 开头。
objectstring: 始终为 invoice。
statusstring: 当前状态。请参阅下方的状态列表。
amountstring: 您要求的价格，以 currency 计。
currencystring: 价格的货币，例如 USD。
amount_usdstring: 以美元计的价格。
descriptionstring | null: 您的描述，会显示给客户。
order_idstring | null: 您自己的订单编号。
customer_emailstring | null: 客户的邮箱（如果您提供了）。
metadataobject: 您在创建账单时传入的对象，原样返回。
coinobject | null: 客户选择的币种，或客户实际支付的币种，包含其 id、symbol 和 network。选择币种之前为 null。
requested_coinobject | null: 通常为 null。当客户使用其他币种或在其他网络上付款且该付款已被计入时，此字段为账单原定的币种，字段与 coin 相同。请参阅错误的币种或错误的网络。
pay_addressstring | null: 此账单的收款地址。选择币种之前为 null。
pay_amountstring | null: 需要发送的准确金额，以所选币种计。
network_fee_amountstring: pay_amount 的一部分：客户在价格之外支付的 Gas 费，以该币种计。没有时为 0。
network_fee_usdstring: 以美元计的同一笔 Gas 费。
rate_usdstring | null: 所选币种一个单位的锁定价格，以美元计。
received_amountstring: 目前已到账的金额，以所选币种计。
received_usdstring: 已到账金额的美元价值。
overpaid_amountstring: 超出账单要求的付款金额，以所选币种计。
refunded_amountstring: 您通过退款链接为这笔付款退款的金额，以所付币种计。未退款时为 0。
checkout_urlstring: 账单页面。将客户引导至此处付款。
redirect_urlstring | null: 客户付款后可前往的地址。
expires_atISO 8601: 如果未检测到付款，账单的过期时间。
paid_atISO 8601 | null: 账单的付款时间，或 null。
created_atISO 8601: 账单的创建时间。

invoice

{
  "id": "inv_…",
  "object": "invoice",
  "status": "open",
  "amount": "49.9",
  "currency": "USD",
  "amount_usd": "49.9",
  "description": "Annual plan",
  "order_id": "1042",
  "customer_email": "[email protected]",
  "metadata": { "plan": "annual" },
  "coin": null,
  "requested_coin": null,
  "pay_address": null,
  "pay_amount": null,
  "network_fee_amount": "0",
  "network_fee_usd": "0",
  "rate_usd": null,
  "received_amount": "0",
  "received_usd": "0",
  "overpaid_amount": "0",
  "refunded_amount": "0",
  "checkout_url": "https://cryptomerchant.online/pay/i/inv_…",
  "redirect_url": "https://yourstore.example/thanks",
  "expires_at": "2026-10-28T10:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-28T09:30:00.000Z"
}

账单状态

open已创建: 已创建。客户尚未选择币种。
awaiting_payment等待付款: 已选择币种，已分配收款地址并锁定汇率。
confirming确认中: 已在链上检测到付款，正在等待确认。
underpaid少付: 已确认的付款短缺超出您的容差。客户可以补付剩余部分或申请退款。
paid已付款: 已付款并确认。扣除手续费后的金额已计入您的余额。部分退款后仍保持此状态。
expired已过期: 在检测到任何付款之前时间已用完。
cancelled已取消: 账单在检测到任何付款之前已被取消。
refunded已退款: 少付账单中客户已发送的金额已退还给客户，或您已将从已付款账单中实得的金额全部退款。

创建账单

POST/invoices

创建账单并以状态码 201 返回账单对象。将客户引导至其 checkout_url。

请求体参数

amount必填number | string: 价格，以数字或十进制字符串表示。价值必须至少为 0.50 美元。
currency可选string: 价格的货币，例如 USD。默认为 USD。
description可选string: 客户所支付的内容，最多 300 个字符。显示在账单页面上。
order_id可选string: 您自己的订单编号，最多 120 个字符，用于将账单与订单对应。
customer_email可选string: 客户的邮箱地址。后台会按客户对付款进行分组。
customer_name可选string: 客户的姓名，最多 120 个字符。
redirect_url可选string: 客户付款后可前往的完整 URL。
metadata可选object: 任意 JSON 对象，最大 4 KB。在账单和 Webhook 中原样返回。
coin可选string: 通过 ID 预选币种，例如 USDT.TRON。必须是您接受的币种之一。

预选 coin 后，收款地址会立即分配并锁定汇率，因此 pay_address 和 pay_amount 会被填入，您可以在自己的界面中显示付款信息。

curl

curl https://cryptomerchant.online/api/v1/invoices \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "currency": "USD",
    "order_id": "1042",
    "description": "Annual plan",
    "customer_email": "[email protected]",
    "redirect_url": "https://yourstore.example/thanks",
    "metadata": { "plan": "annual" }
  }'

Node.js

const res = await fetch("https://cryptomerchant.online/api/v1/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CM_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: "49.90",
    currency: "USD",
    order_id: "1042",
    description: "Annual plan",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const invoice = await res.json();
// Send the customer to invoice.checkout_url

列出账单

GET/invoices

分页返回您的账单，最新的在前。

查询参数

status可选string: 仅返回此状态的账单，例如 paid。必须是上述状态之一。
limit可选number: 返回的账单数量，1 到 100。默认为 20。
starting_after可选string: 一个账单 ID。返回排在其后的账单，用于获取下一页。

账单位于 data 中。当 has_more 为 true 时，将 starting_after 设置为您收到的最后一张账单的 ID 以请求下一页。

curl

curl "https://cryptomerchant.online/api/v1/invoices?status=paid&limit=20" \
  -H "Authorization: Bearer $CM_SECRET_KEY"

响应

{
  "object": "list",
  "data": [
    { "id": "inv_…", "object": "invoice", "status": "paid", … }
  ],
  "has_more": true
}

获取账单

GET/invoices/{id}

按 ID 返回一张账单。

curl

curl https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $CM_SECRET_KEY"

取消账单

POST/invoices/{id}/cancel

取消一张账单。仅当账单未付款且尚未检测到任何付款时有效。

curl

curl -X POST https://cryptomerchant.online/api/v1/invoices/$INVOICE_ID/cancel \
  -H "Authorization: Bearer $CM_SECRET_KEY"

余额

GET/balances

返回您的商家持有的每种币的数量、以美元计的总额，以及您的 Gas 余额。

data[].coin: 币种 ID，例如 USDT.TRON。
data[].symbol: 币种符号，例如 USDT。
data[].network: 该币所在的网络。
data[].amount: 您持有的该币数量，以十进制字符串表示。
data[].usd: 按当前价格计算的美元价值。
total_usd: 您所有币的美元总价值。
gas_balance_usd: 您的 Gas 余额（美元），用于支付 Gas 费。

curl

curl https://cryptomerchant.online/api/v1/balances \
  -H "Authorization: Bearer $CM_SECRET_KEY"

响应

{
  "object": "balance",
  "data": [
    { "coin": "USDT.TRON", "symbol": "USDT", "network": "Tron", "amount": "…", "usd": "…" }
  ],
  "total_usd": "…",
  "gas_balance_usd": "…"
}

接受的币种

GET/coins

返回您当前接受的币种，每个币种都包含 id、symbol、name、network 和 decimals。创建账单时，将 id 作为 coin 使用。例如：

curl

curl https://cryptomerchant.online/api/v1/coins \
  -H "Authorization: Bearer $CM_SECRET_KEY"

响应

{
  "object": "list",
  "data": [
    {
      "id": "ETH.ETH",
      "symbol": "ETH",
      "name": "Ethereum",
      "network": "Ethereum",
      "decimals": 18
    },
    {
      "id": "USDT.ETH",
      "symbol": "USDT",
      "name": "Tether USD",
      "network": "Ethereum",
      "decimals": 6
    },
    {
      "id": "USDC.ETH",
      "symbol": "USDC",
      "name": "USD Coin",
      "network": "Ethereum",
      "decimals": 6
    }
  ]
}

创建支付链接

POST/payment-links

创建支付链接并以状态码 201 返回，包括其 id 和可分享的 url。

请求体参数

title必填string: 客户所支付内容的名称，最多 120 个字符。
amount可选number | string: 固定价格。省略此项可让客户输入金额。
currency可选string: 价格的货币。默认为 USD。
description可选string: 向客户显示的更多详情，最多 300 个字符。

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting hour",
    "amount": "80",
    "currency": "USD"
  }'

响应

{
  "id": "…",
  "object": "payment_link",
  "title": "Consulting hour",
  "description": null,
  "amount": "80",
  "currency": "USD",
  "active": true,
  "url": "https://cryptomerchant.online/pay/l/…",
  "created_at": "2026-10-28T09:30:00.000Z"
}

列出支付链接

GET/payment-links

在 data 中返回您最近的 100 个支付链接，最新的在前。

curl

curl https://cryptomerchant.online/api/v1/payment-links \
  -H "Authorization: Bearer $CM_SECRET_KEY"

提现对象

提现 Webhook（payout.sent 和 payout.failed）在 data 中携带此对象。收入分成中合作伙伴分成的提现使用同一对象，并将 partner_share 设为 true。

idstring: 提现 ID。
objectstring: 始终为 payout。
coinstring: 币种 ID，例如 USDT.TRON。
amountstring: 提现金额，以该币种计。
network_feestring: 发送所需的 Gas 费，以该币种计。
to_addressstring: 提现发送到的钱包地址。
statusstring: queued、running、done 或 failed。
tx_hashstring | null: 发送后在区块链上的交易 ID。
autoboolean: 如果提现是自动进行的，而不是由人发起的，则为 true。
partner_shareboolean: 如果这笔提现是收入分成中的合作伙伴分成，并发送到合作伙伴的钱包，则为 true。
created_atISO 8601: 提现的创建时间。

payout

{
  "id": "…",
  "object": "payout",
  "coin": "USDT.TRON",
  "amount": "120",
  "network_fee": "…",
  "to_address": "T…",
  "status": "done",
  "tx_hash": "…",
  "auto": true,
  "partner_share": true,
  "created_at": "2026-10-28T09:30:00.000Z"
}

接下来，设置 Webhook，让您的服务器在付款发生的第一时间获知。