文档
blockwallets 帮你收 USDT / USDC,以及 BTC、LTC 和各链原生币(按锁定汇率折成美元入账)。下面每种接入方式建出来的都是同一种账单、同一个收银台,确认、费率和余额都一样,区别只在你的系统怎么跟我们对接。挑一种合适的,再看它的详细页。
选一种接入方式
按你从哪里起步分组。点卡片看完整说明。
不写代码
在商户后台就能收款,什么都不用装。
填个金额(或让付款人自己填),把链接或二维码发出去。每打开一次生成一张新账单。
查看 → POS 收银店员在手机或平板上打开 POS 链接,输入金额,顾客扫码付款。
查看 → 嵌入按钮把「付款」「捐赠」按钮贴进任何网站:纯 HTML,或 HTML 加一行脚本。
查看 →新接入 API
从零写接入代码。
Bearer 密钥、金额按美分、ref 防重、HMAC-SHA256 回调和事件接口。密钥在商户后台自助生成。
POST + JSON,md5 签名。凭据在商户后台自助生成,关键接口都有「试一下」面板。
查看 →从别的平台迁移
代码不用重写:接口兼容,换基础地址和密钥就行。
把 https://api.cryptomus.com 换成 https://blockwallets.io,换上新的 merchant 和 API key。路径、参数、sign 和回调都不变。
把 https://api.nowpayments.io/v1 换成 https://blockwallets.io/nowpayments/v1,换上新的 API key 和 IPN secret。x-nowpayments-sig 不变。
SDK 的 base URL 传 https://blockwallets.io/coinbase/,换上新的 API key 和 webhook shared secret。X-CC-Webhook-Signature 不变。
让 AI 帮你接
不会写代码、但会用 AI 编程工具的人。
选好网站、收款方式和 AI 工具,复制它生成的提示词,交给 Claude Code、Codex、Cursor 或 ChatGPT。
查看 → AGENTS.md接入规则、易错点和验收清单;放在项目根目录给编程 agent 读。
查看 → MCP server让 AI 工具直接查这些文档、建测试账单。
查看 →工具
在浏览器里跑的调试帮手。
Cryptomus 兼容还是原生?
两种建出来的是同一种账单、同一个收银台,费率和余额都一样。区别在请求写法、回调格式,以及凭据怎么拿。
| Cryptomus 兼容 | 原生 REST | |
|---|---|---|
| 凭据 | 在商户后台「开发者 › 接入与密钥」自己生成(正式、测试各一套) | 也在商户后台「开发者 › 接入与密钥」自己生成:正式和测试各一把密钥(bw_live_… / bw_test_…)和对应的回调签名密钥 |
| 请求 | 一律 POST + JSON,请求头 merchant 和 sign = md5(base64(请求体) + API key) | REST(GET / POST),Authorization: Bearer;密钥前缀决定 Live 还是 Test |
| 金额 | 小数字符串,如 "42.00",USD、USDT 或 USDC(都是 1:1) | 美分整数,如 4200;只收 USD |
| 重试 | 同一个 order_id 返回已有的账单 | 同一个 ref、同样的参数返回已有的发票;参数不同回 409 |
| 回调 | 发到每张账单的 url_callback;签名是请求体里的 sign 字段 | 发到商户后台设的回调地址;X-BW-Signature = 带时间戳的 HMAC-SHA256;用 /v1/events 查投递、重投 |
| 静态地址 | /v1/wallet:一次一个网络 | /v1/deposit-accounts:一个用户一次拿到所有网络的地址 |
| 配套工具 | 「试一下」面板、在线验签、AI 提示词和 MCP server;现成的 Cryptomus SDK、插件都能用 | 本参考页和里面的代码示例 |
新接入推荐原生 REST 接口:金额按美分、ref 防重、回调带时间戳签名,密钥在后台自己生成。已经接过 Cryptomus,或想直接用现成的 Cryptomus SDK、插件,选 Cryptomus 兼容接口。
快速开始
从零到一笔测试付款,五步(以 Cryptomus 兼容接口为例;另外几种接口步骤一样,换成各自的凭据)。
- 在首页申请开通;通过后登录商户后台。
- 打开后台「开发者 › 接入与密钥」,在测试那一列生成 merchant 和 API key,填上你的网站域名。
- 你的服务器调
POST /v1/payment建一张账单,把用户跳到result.url。 - 在收银台点「模拟付款」付掉它,确认你的回调处理验过
sign、按payment_amount_usd入账。 - 换成正式那一列的凭据,真付一小笔走一遍(后台首页「试一笔」)。
POST https://blockwallets.io/v1/payment
merchant: <merchant>
sign: md5(base64(body) + API key)
Content-Type: application/json
{
"amount": "42.00",
"currency": "USD",
"order_id": "order_1042",
"url_callback": "https://shop.example/webhooks/crypto",
"url_return": "https://shop.example/cart",
"url_success": "https://shop.example/thanks?order=1042"
}每一步的 Node.js、PHP、Python 代码见 Cryptomus 兼容接口文档;想让 AI 来做,从提示词生成器开始。
收款链接(不写代码)
商户后台 →「收款 › 收款链接」→ 填收款说明和金额(可以固定网络,也可以让用户自己选)→ 创建。每个链接有一个网址和一个二维码。
- 每次有人打开链接,都会生成一张新账单,所以一个链接可以反复用(比如「会员费 $99」)。
- 收到的钱在「收款 › 收款记录」里能看到每一笔,在「资金 › 余额与提现」里提到你的钱包。
- 在「开发者 › 接入与密钥」生成了凭据、填了回调地址的话,链接上的每笔到账也会按 Cryptomus 兼容的回调格式通知你。
- 不想再收了,点「停用」,链接立刻失效。
POS 收银
给柜台、摊位用:商户后台 →「收款 › POS 收银」→ 开一个终端,拿到 POS 链接。店员在手机或平板上打开,输入金额就出付款二维码;顾客付完,屏幕显示「已到账」。
- POS 建的账单 30 分钟内有效。钱进你的余额、出现在「收款 › 收款记录」里,并像收款链接一样回调你的回调地址。
- POS 链接只能收款:看不到余额、提现、别的订单、设置和凭据。
- 设备丢了或店员离职?在后台撤销那个终端,它的链接立刻失效。
嵌入按钮
商户后台 →「收款 › 收款链接」→「嵌入按钮」:选好文字、颜色、大小和形状,复制代码。点按钮打开这个收款链接的收银台。
- 纯 HTML:一个写好样式的链接,没有脚本,能贴 HTML 的地方都能用(建站工具、论坛、邮件签名)。
- 带脚本:加上
data-blockwallets和一行/embed.js;电脑上在居中的小窗打开收银台,手机上照常打开。 - 脚本不发请求、不写 cookie、不建 iframe;对方页面拦了脚本,按钮照样是个能用的普通链接。
下面的代码里,把 /l/pl_… 换成你自己的收款链接地址。
纯 HTML
<a href="https://blockwallets.io/l/pl_…" target="_blank" rel="noopener nofollow"
style="display:inline-flex;align-items:center;height:44px;padding:0 22px;border-radius:999px;background:#1f5a3d;color:#ffffff;font:600 16px/1 sans-serif;text-decoration:none">Pay with crypto</a>HTML + 脚本
<a href="https://blockwallets.io/l/pl_…" target="_blank" rel="noopener nofollow"
data-blockwallets data-color="green" data-size="m" data-shape="pill">Pay with crypto</a>
<script src="https://blockwallets.io/embed.js" async></script>