Coinbase

Gereken bilgiler

Bu entegrasyon Coinbase Business Checkouts API'sini kullanır (eski Coinbase Commerce "charge" API'si kapatıldı; onun X-CC-Api-Key anahtarları burada çalışmaz). Bir Coinbase Business hesabı gerekir; ödemeler doğrudan bu hesaba USDC olarak düşer.

1. API anahtarı: Coinbase Developer Platform → API Keys → Secret API Keys → Create API key. İzin olarak View yeterlidir (Checkouts API bu kapsamdadır). İmza algoritması olarak Ed25519 (varsayılan) ya da ECDSA seçilebilir; ikisi de desteklenir.

• api_key: API anahtarının ID'si (Ed25519'da UUID biçiminde; ECDSA'da organizations/…/apiKeys/…)
• secret_key: anahtarın secret'ı (Ed25519'da tek satır base64; ECDSA'da -----BEGIN EC PRIVATE KEY----- ile başlayan PEM, satır sonlarını \n olarak yapıştırabilirsiniz)

2. Webhook aboneliği: Coinbase, checkout durum değişikliklerini yalnız bir webhook aboneliğine gönderir ve bu abonelik sizin tarafınızda oluşturulmalıdır. Coinbase'in belgelediği yol CDP CLI'dır:

cdp data webhooks subscriptions create \
  description="Panel checkout webhook" \
  'eventTypes:=["checkout.payment.success","checkout.payment.failed","checkout.payment.expired","checkout.refund.success","checkout.refund.failed"]' \
  target.url=https://<panel-alan-adınız>/payments/coinbase/callback \
  target.method=POST \
  isEnabled:=true

Yanıttaki metadata.secret değeri:

• webhook_secret: webhook imza sırrı

Panelinizde Ayarlar → Ödemeler → Yöntem ekle → Coinbase seçin, üç değeri girin.

Test ortamı yoktur: Coinbase Business Checkouts için ayrı bir sandbox adresi belgelenmemiştir; istekler her zaman business.coinbase.com'a gider ve "test modu" kutusunun bir etkisi olmaz. Küçük tutarlı gerçek bir ödemeyle deneyin.

Akış

1. Müşteri tutarı girer, Coinbase'i seçer. Panel, panelinizin para birimiyle tek kullanımlık bir checkout oluşturur; Coinbase fiat tutarı o anki kurla USDC'ye çevirir (24 saat geçerli).
2. Müşteri Coinbase'in ödeme sayfasına yönlendirilir; cüzdanından ya da Coinbase hesabından öder.
3. Ödeme sonrası müşteri panele geri döner. Bu dönüş bakiye yüklemez: Coinbase'in belgesine göre o anda checkout hâlâ ACTIVE olabilir.
4. Coinbase zincirde ödemeyi görünce checkout.payment.success webhook'unu X-Hook0-Signature imzasıyla gönderir. Panel imzayı webhook_secret ile doğrular, metadata.publicRef alanındaki ödeme numarası bizimse bakiyeyi yükler ve Coinbase'e OK döner.
5. checkout.payment.failed ödemeyi başarısız, checkout.payment.expired süresi dolmuş yapar.

Aynı checkout için tekrar gelen aynı olay yok sayılır; bakiye iki kez yüklenmez.

Durumlar

Coinbase olayı	Panel
checkout.payment.success	tamamlandı, bakiye yüklendi
checkout.payment.failed	başarısız
checkout.payment.expired	süresi doldu
checkout.refund.success / checkout.refund.failed	kayıt değişmez; iade Coinbase Business panelinden yönetilir, bakiyeyi Admin → Ödemeler'den elle düzeltin

Checkouts API'de "eksik ödeme" diye bir durum yoktur: Coinbase ödemeyi ya tamamlar ya FAILED sayar. Yüklenen tutar, checkout'u oluşturduğumuz fiat tutardır (USDC'ye çevrim ve Coinbase komisyonu sizin Coinbase hesabınızda görünür, müşterinin bakiyesini etkilemez).

Para birimleri

Checkout, panelinizin para birimiyle açılır. Coinbase belgesi USDC ile USD, EUR, GBP, SGD ve "diğer fiat para birimlerini" sayar; tam listeyi yayımlamaz. Coinbase'in kabul etmediği bir birimde checkout açılamaz ve Coinbase'in hata mesajı ödeme başlatılırken görünür. Tutar 0,01–100.000.000 USD aralığında ve en çok 2 ondalıklı olmalıdır.

Sık sorunlar

• "The request is not properly authenticated (unauthorized)": api_key/secret_key uyuşmuyor ya da anahtar başka bir CDP projesine ait. Secret'ı tam olarak (PEM ise BEGIN/END satırları dâhil) yapıştırın; IP allowlist tanımladıysanız sunucu IP'niz listede olmalı.
• Ödeme yapıldı ama bakiye yok: Webhook aboneliği yok, yanlış adrese gidiyor ya da webhook_secret farklı. cdp data webhooks subscriptions events <ID> ile teslimatları görün; imza tutmazsa panel 400 döner ve Coinbase yeniden dener.
• Müşteri döndü, bakiye birkaç dakika gecikti: Normaldir; dönüş sayfası bakiye yüklemez, Coinbase ödemeyi zincirde onaylayınca webhook gelir ve kayıt tamamlanır.
• Coinbase para birimini reddediyor (invalid_request): panel para biriminiz Coinbase'in kabul ettikleri arasında değil; Coinbase yöntemini yalnız desteklenen bir birimde kullanın.