# Coinbase Commerce uyumlu API

> Coinbase Commerce'ten blockwallets'a SDK temel URL'sini ve anahtarları değiştirerek geçin: desteklenen charge endpoint'leri, webhook'lar ve imzalar, ve farklar.
>
> HTML: https://blockwallets.io/docs/coinbase-commerce?lang=tr · English: https://blockwallets.io/docs/coinbase-commerce.md?lang=en

## Coinbase Commerce uyumlu API

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](https://blockwallets.io/docs/migrate?lang=tr) 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](https://blockwallets.io/?lang=tr#join)) 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.

```nodejs
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](https://blockwallets.io/docs/cryptomus?lang=tr) gibi çalışır.