Coinbase Commerce 兼容接口

在 ChatGPT 中打开在 Claude 中打开

charge 接口、X-CC-Api-Key 请求头、charge 对象和用 X-CC-Webhook-Signature 签名的 webhook 都照 Coinbase Commerce 官方文档,官方 SDK 改一行就能用。Coinbase Commerce 已于 2026-03-31 停止服务美国、新加坡以外的商户。从别家迁过来?看迁移总览。

底层就是 blockwallets 的账单:收款地址是你自己的,付款页是我们的收银台,到账后链上确认、再找第二家节点核对一遍才算付款成功。下面先讲三步接入,再分别列出两家的支持范围和与官方接口的差异——没实现的参数会明确报错,不会悄悄忽略。

三步接入

开通商户(首页申请),在商户后台「开发者 › 接入与密钥」的「网站域名」里填上你的域名。回调地址(ipn_callback_url)和跳转地址(success_url / cancel_url / redirect_url)只接受这些域名和回调地址的域名——即使密钥泄露,也没法把回调指到别处。
在商户后台「开发者 › 接入与密钥」页生成兼容凭据(live 和 test 各一套):NOWPayments 是 API key + IPN secret,Coinbase Commerce 是 API key + webhook shared secret。密钥只显示一次,我们这边只存哈希 / 密文。
把代码里的 base URL 换成下面的地址,换上新密钥。先用 test 凭据在测试网走一遍,再换 live。

原来	换成	鉴权头	回调签名
`https://api.commerce.coinbase.com`	`https://blockwallets.io/coinbase/`	`X-CC-Api-Key`	`X-CC-Webhook-Signature`(HMAC-SHA256)

Coinbase Commerce

官方 SDK 都能配 base URL,改一行即可(注意结尾的 /):

SDK

// Node(coinbase-commerce-node)
const { Client } = require("coinbase-commerce-node");
- Client.init(process.env.COINBASE_COMMERCE_API_KEY);
+ Client.init(process.env.COINBASE_COMMERCE_API_KEY, "https://blockwallets.io/coinbase/");

# Python(coinbase-commerce)
- client = Client(api_key=API_KEY)
+ client = Client(api_key=API_KEY, base_api_uri="https://blockwallets.io/coinbase/")

// PHP(coinbase/coinbase-commerce)
- ApiClient::init($apiKey);
+ ApiClient::init($apiKey, 'https://blockwallets.io/coinbase/');

curl

curl -X POST https://blockwallets.io/coinbase/charges \
  -H "X-CC-Api-Key: $COINBASE_COMMERCE_API_KEY" -H "X-CC-Version: 2018-03-22" \
  -H "content-type: application/json" \
  -d '{"name":"Order #12345","description":"Pro plan","pricing_type":"fixed_price",
       "local_price":{"amount":"100.00","currency":"USD"},
       "redirect_url":"https://shop.example/success","cancel_url":"https://shop.example/cancel",
       "metadata":{"order_id":"12345"}}'
# → 201 {"data": {"id": "…", "code": "7C7V5ECK", "hosted_url": "https://blockwallets.io/pay/inv_…", "timeline": [{"status": "NEW", …}], …}}

支持的接口

接口	说明
`POST /charges`	建 charge,`hosted_url` 是我们的收银台;有效 1 小时
`GET /charges/:code_or_id`	按 8 位 code 或 id 查
`GET /charges`	列表:`limit`(≤100)/ `starting_after` / `ending_before` / `order`,返回同样的 `pagination` 对象
`POST /charges/:code_or_id/cancel`	取消还没见到付款的 charge

没有:/charges/:code/resolve(返回 400,少付的单在商户后台处理)、/checkouts、/events、/invoices(返回 404)。

Webhook

Coinbase 的 webhook 地址是账户级的,我们也一样:发往你在商户后台填的回调地址(test 凭据建的单发往 test 回调地址)。body 是 Coinbase 的 {id, scheduled_for, attempt_number, event: {id, type, api_version, created_at, data}},data 是完整的 charge;头 X-CC-Webhook-Signature = HMAC-SHA256(shared secret, 原始 body),官方 SDK 的 Webhook.verifyEventBody 直接能用。重投时 event.id 不变、attempt_number 加一,按 event.id 去重即可。

Node.js

import crypto from "node:crypto";

// 和官方 SDK 的 Webhook.verifySigHeader 一样:HMAC-SHA256(shared secret, 原始 body)
function verifyWebhook(rawBody, sig, sharedSecret) {
  const hmac = crypto.createHmac("sha256", sharedSecret).update(rawBody, "utf8").digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(sig || ""));
}
// verifyWebhook(rawBody, req.headers["x-cc-webhook-signature"], process.env.COINBASE_WEBHOOK_SECRET)
// 官方 SDK 照用:Webhook.verifyEventBody(rawBody, signature, sharedSecret)

事件	什么时候	timeline 最后一项
`charge:confirmed`	已收款(链上确认并核对过;多付也算)	`COMPLETED`
`charge:failed`	到期没付 / 你取消了 / 到期时收到的不够	`EXPIRED` / `CANCELED` / `UNRESOLVED`(context `UNDERPAID`)

查单时还能看到 NEW(等待付款)和 PENDING(链上见到付款、在等确认)。请按 charge:confirmed 发货:我们不发 charge:created、charge:pending、charge:delayed、charge:resolved。

与 Coinbase Commerce 的差异

pricing_type 只支持 fixed_price;local_price.currency 只支持 USD(USDC / USDT 按 1:1)。no_price 和其他法币返回 400。
付款人在收银台选币种和网络后才有地址:addresses 只有选中的那一个网络,pricing 只有 local 和选中后的 settlement;没有 exchange_rates、checkout、品牌设置。
metadata 原样保存、原样返回(最多 4 KB)。
退款不出现在 timeline 里,在商户后台看。

测试模式

test 凭据建的单走各链的测试网,回调用 test 的 IPN secret / shared secret 签名,和 live 完全隔离:test 的 key 查不到 live 的单。

其余细节(收银台、确认数、网络与最低金额、退款)和主文档一样。