# blockwallets 文档:接入方式总览 > 选一种接入方式:不写代码的收款链接、POS、嵌入按钮;Cryptomus 兼容接口或原生 REST 接口;Cryptomus、NOWPayments、Coinbase Commerce 兼容接口;AI 提示词、AGENTS.md 和 MCP。 > > HTML: https://blockwallets.io/docs · English: https://blockwallets.io/docs.md?lang=en ## 文档 blockwallets 帮你收 USDT / USDC,以及 BTC、LTC 和各链原生币(按锁定汇率折成美元入账)。下面每种接入方式建出来的都是同一种账单、同一个收银台,确认、费率和余额都一样,区别只在你的系统怎么跟我们对接。挑一种合适的,再看它的详细页。 ### 选一种接入方式 按你从哪里起步分组。点卡片看完整说明。 #### 不写代码 在商户后台就能收款,什么都不用装。 - [收款链接](https://blockwallets.io/docs#links): 填个金额(或让付款人自己填),把链接或二维码发出去。每打开一次生成一张新账单。 - [POS 收银](https://blockwallets.io/docs#pos): 店员在手机或平板上打开 POS 链接,输入金额,顾客扫码付款。 - [嵌入按钮](https://blockwallets.io/docs#embed): 把「付款」「捐赠」按钮贴进任何网站:纯 HTML,或 HTML 加一行脚本。 #### 新接入 API 从零写接入代码。 - [原生 REST 接口](https://blockwallets.io/docs/api?lang=zh): Bearer 密钥、金额按美分、`ref` 防重、HMAC-SHA256 回调和事件接口。密钥在商户后台自助生成。 - [Cryptomus 兼容接口](https://blockwallets.io/docs/cryptomus?lang=zh): POST + JSON,md5 签名。凭据在商户后台自助生成,关键接口都有「试一下」面板。 #### 从别的平台迁移 代码不用重写:接口兼容,换基础地址和密钥就行。 - [从 Cryptomus 迁移](https://blockwallets.io/docs/cryptomus?lang=zh#cryptomus): 把 `https://api.cryptomus.com` 换成 `https://blockwallets.io`,换上新的 merchant 和 API key。路径、参数、`sign` 和回调都不变。 - [从 NOWPayments 迁移](https://blockwallets.io/docs/nowpayments?lang=zh): 把 `https://api.nowpayments.io/v1` 换成 `https://blockwallets.io/nowpayments/v1`,换上新的 API key 和 IPN secret。`x-nowpayments-sig` 不变。 - [从 Coinbase Commerce 迁移](https://blockwallets.io/docs/coinbase-commerce?lang=zh): SDK 的 base URL 传 `https://blockwallets.io/coinbase/`,换上新的 API key 和 webhook shared secret。`X-CC-Webhook-Signature` 不变。 #### 让 AI 帮你接 不会写代码、但会用 AI 编程工具的人。 - [提示词生成器](https://blockwallets.io/docs/ai?lang=zh): 选好网站、收款方式和 AI 工具,复制它生成的提示词,交给 Claude Code、Codex、Cursor 或 ChatGPT。 - [AGENTS.md](https://blockwallets.io/agents.md): 接入规则、易错点和验收清单;放在项目根目录给编程 agent 读。 - [MCP server](https://blockwallets.io/docs/mcp?lang=zh): 让 AI 工具直接查这些文档、建测试账单。 #### 工具 在浏览器里跑的调试帮手。 - [在线验签](https://blockwallets.io/docs/sign?lang=zh): 贴请求体或回调体,逐步列出签名的每一步、标出你哪里不一样。API key 不出浏览器。 ### 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 兼容接口为例;另外几种接口步骤一样,换成各自的凭据)。 - 在[首页](https://blockwallets.io/?lang=zh#join)申请开通;通过后登录[商户后台](https://blockwallets.io/dashboard)。 - 打开后台「开发者 › 接入与密钥」,在测试那一列生成 merchant 和 API key,填上你的网站域名。 - 你的服务器调 `POST /v1/payment` 建一张账单,把用户跳到 `result.url`。 - 在收银台点「模拟付款」付掉它,确认你的回调处理验过 `sign`、按 `payment_amount_usd` 入账。 - 换成正式那一列的凭据,真付一小笔走一遍(后台首页「试一笔」)。 ```http POST https://blockwallets.io/v1/payment 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 兼容接口](https://blockwallets.io/docs/cryptomus?lang=zh#api)文档;想让 AI 来做,从[提示词生成器](https://blockwallets.io/docs/ai?lang=zh)开始。 ### 收款链接(不写代码) 商户后台 →「收款 › 收款链接」→ 填收款说明和金额(可以固定网络,也可以让用户自己选)→ 创建。每个链接有一个网址和一个二维码。 - 每次有人打开链接,都会生成一张新账单,所以一个链接可以反复用(比如「会员费 $99」)。 - 收到的钱在「收款 › 收款记录」里能看到每一笔,在「资金 › 余额与提现」里提到你的钱包。 - 在「开发者 › 接入与密钥」生成了凭据、填了回调地址的话,链接上的每笔到账也会按 [Cryptomus 兼容的回调格式](https://blockwallets.io/docs/cryptomus?lang=zh#webhooks)通知你。 - 不想再收了,点「停用」,链接立刻失效。 ### POS 收银 给柜台、摊位用:商户后台 →「收款 › POS 收银」→ 开一个终端,拿到 POS 链接。店员在手机或平板上打开,输入金额就出付款二维码;顾客付完,屏幕显示「已到账」。 - POS 建的账单 30 分钟内有效。钱进你的余额、出现在「收款 › 收款记录」里,并像收款链接一样回调你的回调地址。 - POS 链接只能收款:看不到余额、提现、别的订单、设置和凭据。 - 设备丢了或店员离职?在后台撤销那个终端,它的链接立刻失效。 ### 嵌入按钮 商户后台 →「收款 › 收款链接」→「嵌入按钮」:选好文字、颜色、大小和形状,复制代码。点按钮打开这个收款链接的收银台。 - 纯 HTML:一个写好样式的链接,没有脚本,能贴 HTML 的地方都能用(建站工具、论坛、邮件签名)。 - 带脚本:加上 `data-blockwallets` 和一行 `/embed.js`;电脑上在居中的小窗打开收银台,手机上照常打开。 - 脚本不发请求、不写 cookie、不建 iframe;对方页面拦了脚本,按钮照样是个能用的普通链接。 下面的代码里,把 `/l/pl_…` 换成你自己的收款链接地址。 #### 纯 HTML ```html Pay with crypto ``` #### HTML + 脚本 ```html Pay with crypto ```