Coinbase Commerce 互換 API

ChatGPT で開く Claude で開く

charge のエンドポイント、X-CC-Api-Key ヘッダー、charge オブジェクト、X-CC-Webhook-Signature で署名される Webhook は Coinbase Commerce のドキュメントに従うため、公式 SDK は 1 行変えるだけで動きます。Coinbase Commerce は 2026-03-31 に、米国とシンガポール以外の加盟店へのサービス提供を終了しました。ほかのサービスからの移行ですか?移行の概要をご覧ください。

内部では通常の blockwallets の請求です。受取アドレスはあなたのもの、決済ページは当社のホスト型決済ページで、支払いはオンチェーンで承認され、2つ目のノードでも照合されて初めて有効になります。以下では、3つのステップに続けて、各 API の対応範囲と元のサービスとの違いを説明します。実装していないパラメーターは、黙って無視されることなくエラーを返します。

3つのステップ

加盟店アカウントを取得し(トップページから申し込み)、管理画面「開発者 › 連携とキー」の「サイトのドメイン」にドメインを追加します。コールバック URL(ipn_callback_url)とリダイレクト URL(success_url / cancel_url / redirect_url)は、これらのドメイン上、またはコールバック URL のドメイン上である必要があります。キーが漏えいしても、Webhook を別の場所に向けることはできません。
加盟店管理画面の「開発者 › 連携とキー」で互換の認証情報を発行します。本番用とテスト用が1組ずつあり、NOWPayments は API key + IPN secret、Coinbase Commerce は API key + webhook shared secret です。表示は一度だけで、当社にはハッシュ / 暗号文だけを保存します。
コードを下記のベース URL に向け、新しいキーを使います。まずテスト用の認証情報でテストネット上で動かし、そのあと本番に切り替えてください。

移行前	移行後	認証ヘッダー	Webhook 署名
`https://api.commerce.coinbase.com`	`https://blockwallets.io/coinbase/`	`X-CC-Api-Key`	`X-CC-Webhook-Signature`(HMAC-SHA256)

Coinbase Commerce

公式 SDK はどれもベース URL を指定できます。1 行変えるだけです(末尾の / に注意):

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`	チャージを作成。`hosted_url` は当社のホスト型決済ページで、有効期間は 1 時間
`GET /charges/:code_or_id`	8 文字のコードまたは id で検索
`GET /charges`	一覧:`limit`(100 以下)/ `starting_after` / `ending_before` / `order`。`pagination` オブジェクトも同じ
`POST /charges/:code_or_id/cancel`	まだ支払いを検知していないチャージをキャンセル

非対応:/charges/:code/resolve(400 — 不足払いのチャージは管理画面で対応してください)、/checkouts、/events、/invoices(404)。

Webhook

Coinbase の Webhook はアカウント単位で、当社も同じです。管理画面で設定したコールバック URL に送信されます(テスト用の認証情報で作成したチャージはテスト用のコールバック URL に送信)。ボディは Coinbase 形式の {id, scheduled_for, attempt_number, event: {id, type, api_version, created_at, data}} で、data にチャージの全内容が入ります。X-CC-Webhook-Signature = HMAC-SHA256(shared secret, 生のボディ) なので、SDK の Webhook.verifyEventBody がそのまま使えます。再試行では event.id は同じままで attempt_number が増えます。event.id で重複を排除してください。

Node.js

import crypto from "node:crypto";

// Same as the SDK's Webhook.verifySigHeader: HMAC-SHA256(shared secret, raw 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)
// or with the official SDK:Webhook.verifyEventBody(rawBody, signature, sharedSecret)

イベント	タイミング	最後のタイムライン項目
`charge:confirmed`	支払済み(オンチェーンで承認され、照合済み。超過払いも含む)	`COMPLETED`
`charge:failed`	未払いのまま期限切れ / あなたがキャンセル / 不足のまま期限切れ	`EXPIRED` / `CANCELED` / `UNRESOLVED`(コンテキスト `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)。
返金はタイムラインに表示されません。管理画面で確認してください。

テストモード

テスト用の認証情報で作成したチャージと決済は各チェーンのテストネットで動き、その Webhook はテスト用の IPN secret / shared secret で署名されます。本番とは完全に分離されており、テスト用のキーから本番の決済は見えません。

そのほか(決済ページ、承認、ネットワークと最低額、返金)はメインのドキュメントのとおりに動作します。