Coinbase Commerce uyumlu API

ChatGPT'de aç Claude'da aç

Charge endpoint'leri, X-CC-Api-Key başlığı, charge nesnesi ve X-CC-Webhook-Signature ile imzalanan webhook'lar Coinbase Commerce dokümanlarını izler; bu yüzden resmî SDK'lar tek satır değiştirildikten sonra çalışır. Coinbase Commerce, 2026-03-31 tarihinde ABD ve Singapur dışındaki satıcılara hizmet vermeyi bıraktı. Başka bir yerden mi geliyorsunuz? Geçişe genel bakışa bakın.

Altta düzenli bir blockwallets faturası vardır: alım adresleri sizindir, ödeme sayfası bizim barındırdığımız ödeme sayfasıdır ve bir ödeme ancak zincirde onaylanıp ikinci bir node ile çapraz kontrol edildiğinde sayılır. Aşağıda: üç adım, ardından her API'nin neyi desteklediği ve orijinalinden nasıl farklı olduğu — uygulamadığımız parametreler sessizce yok sayılmak yerine hata döndürür.

Üç adım

Bir satıcı hesabı edinin (ana sayfadan başvurun) ve panelde “Geliştiriciler › Entegrasyon ve anahtarlar” sayfasındaki “Web sitesi alan adları” altına alan adlarınızı ekleyin. Callback URL'leri (ipn_callback_url) ve yönlendirme URL'leri (success_url / cancel_url / redirect_url) bu alan adlarında ya da callback URL'nizin alan adında olmalıdır — sızan bir anahtar webhook'ları başka yere yönlendiremez.
Satıcı panelinde “Geliştiriciler › Entegrasyon ve anahtarlar” altında uyumlu kimlik bilgileri oluşturun; canlı için bir, test için bir takım: NOWPayments için bir API key + IPN secret, Coinbase Commerce için bir API key + webhook shared secret. Bir kez gösterilirler; biz yalnızca hash / şifreli metin saklarız.
Kodunuzu aşağıdaki temel URL'ye yönlendirin ve yeni anahtarları kullanın. Önce test kimlik bilgileriyle testnet'lerde çalıştırın, sonra canlıya geçin.

Önce	Sonra	Kimlik doğrulama başlığı	Webhook imzası
`https://api.commerce.coinbase.com`	`https://blockwallets.io/coinbase/`	`X-CC-Api-Key`	`X-CC-Webhook-Signature` (HMAC-SHA256)

Coinbase Commerce

Tüm resmî SDK'lar bir temel URL alır — tek satırı değiştirin (sondaki / karakterine dikkat):

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", …}], …}}

Desteklenen endpoint'ler

Endpoint	Notlar
`POST /charges`	Charge oluşturur; `hosted_url` bizim barındırdığımız ödeme sayfasıdır; 1 saat geçerlidir
`GET /charges/:code_or_id`	8 karakterlik kod veya id ile sorgular
`GET /charges`	Liste: `limit` (≤100) / `starting_after` / `ending_before` / `order`, aynı `pagination` nesnesiyle
`POST /charges/:code_or_id/cancel`	Henüz ödeme görülmemiş bir charge'ı iptal eder

Mevcut değil: /charges/:code/resolve (400 — eksik ödenen charge'ları panelden yönetin), /checkouts, /events, /invoices (404).

Webhook'lar

Coinbase webhook'ları hesap düzeyindedir, bizimkiler de öyle: panelinizde belirlenen callback URL'ye gider (test kimlik bilgileriyle oluşturulan charge'lar test callback URL'sine gider). Gövde, Coinbase'in {id, scheduled_for, attempt_number, event: {id, type, api_version, created_at, data}} biçimidir ve charge'ın tamamı data içindedir; X-CC-Webhook-Signature = HMAC-SHA256(shared secret, ham gövde), yani SDK'ların Webhook.verifyEventBody işlevi olduğu gibi çalışır. Yeniden denemelerde event.id aynı kalır ve attempt_number artar — event.id ile tekilleştirin.

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)

Olay	Ne zaman	Zaman çizelgesindeki son kayıt
`charge:confirmed`	Ödendi (zincirde onaylandı ve çapraz kontrol edildi; fazla ödeme dahil)	`COMPLETED`
`charge:failed`	Ödenmeden süresi doldu / sizin tarafınızdan iptal edildi / eksik ödenip süresi doldu	`EXPIRED` / `CANCELED` / `UNRESOLVED` (bağlam `UNDERPAID`)

Sorguladığınızda ayrıca NEW (ödeme bekleniyor) ve PENDING (ödeme zincirde görüldü, onaylanıyor) göreceksiniz. charge:confirmed olayında siparişi yerine getirin: charge:created, charge:pending, charge:delayed veya charge:resolved göndermiyoruz.

Coinbase Commerce'ten farklar

pricing_type fixed_price olmalıdır; local_price.currency USD olmalıdır (USDC / USDT 1:1). no_price ve diğer fiat para birimleri 400 döndürür.
Adres, müşteri ödeme sayfasında bir coin ve ağ seçtiğinde görünür: addresses yalnızca o ağı içerir, pricing yalnızca local ve seçildikten sonra settlement içerir; exchange_rates, checkout veya marka alanları yoktur.
metadata olduğu gibi saklanır ve döndürülür (en çok 4 KB).
İadeler zaman çizelgesinde görünmez; panelde görün.

Test modu

Test kimlik bilgileriyle oluşturulan charge'lar ve ödemeler her zincirin testnet'inde çalışır ve webhook'ları test IPN secret / shared secret ile imzalanır — canlıdan tamamen ayrıdır: bir test anahtarı canlı ödemeleri göremez.

Geri kalan her şey (ödeme sayfası, onaylar, ağlar ve asgari tutarlar, iadeler) ana dokümanlardaki gibi çalışır.