CoinPayments

Gereken bilgiler

Bu sürücü CoinPayments'ın yeni platformunu (docs.coinpayments.net, API v2) kullanır; eski api.php / IPN entegrasyonu ile ilgisi yoktur. Eski "Merchant ID + IPN Secret" bilgileri burada çalışmaz.

CoinPayments Dashboard → Integrations → Add Integration → API Integrations. Entegrasyon oluşturulunca gösterilen iki değeri panelinize girin:

• client_id: entegrasyonun clientId değeri
• secret_key: entegrasyonun clientSecret değeri (yalnız bir kez gösterilir; kaybolursa dashboard'dan yenilenir)

Panelinizde Ayarlar → Ödemeler → Yöntem ekle → CoinPayments seçin.

Örnek (instance): CoinPayments hesapları üç üretim örneğinden birinde yaşar (A: a-api.coinpayments.net, B: b-api…, C: c-api…) ve bilgiler örnekler arasında taşınmaz. Sürücü varsayılan olarak A örneğini kullanır; hesabınız B ya da C'deyse panel ekibine bildirin (yöntem ayarlarında instance değeri).

Sandbox: sandbox (test) modu kutusu işaretliyken istekler api.coinpayments.net sandbox örneğine gider. Ayrıca CoinPayments'ın ücretsiz LTCT test koinini (Dashboard → Balances → Get Free LTCT) kullanabilirsiniz; canlıya geçmeden LTCT'yi Payment Settings'ten kapatın.

Callback (webhook)

Callback bir sunucu webhook'udur; müşterinin tarayıcısı değil, CoinPayments'ın sunucuları çağırır. Adresi her faturaya otomatik eklenir (fatura başına webhook), CoinPayments dashboard'unda ayrıca tanımlamak gerekmez. Adres kalıbı:

https://<panel-alan-adınız>/payments/coinpayments/callback

Dashboard'daki entegrasyona da webhook eklerseniz birebir aynı adresi yazın (sonda / yok, http değil https): imza bu adres üzerinden hesaplanır, farklı yazılırsa doğrulama başarısız olur.

Alan adınızın geçerli bir SSL sertifikası olmalı; CoinPayments yalnız https adreslere gönderir.

Akış

1. Müşteri tutarı girer, CoinPayments'ı seçer. Fatura panelinizin para biriminde (ör. 250 TRY) oluşturulur; fatura numarası bizim ödeme referansımızdır.
2. Müşteri CoinPayments'ın ödeme sayfasına yönlendirilir, orada koini seçer (BTC, ETH, USDT vb.) ve gönderir. Kur 60 dakika sabit kalır.
3. Zincirdeki her onayda CoinPayments panelinize webhook gönderir; ödeme "beklemede" görünür, notunda onay sayısı yazar.
4. Fatura completed olduğunda (fon CoinPayments hesabınıza geçtiğinde) bakiye yüklenir. Her webhook'un imzası secret_key ile doğrulanır; imzasız ya da başka bir entegrasyondan gelen istek yok sayılır.
5. Müşterinin tarayıcısı successUrl ile panele dönebilir; bu dönüş bakiye yüklemez, yalnız sayfayı gösterir.

Aynı fatura için tekrar gelen completed webhook'u yok sayılır; bakiye iki kez yüklenmez.

Durumlar

CoinPayments olayı / fatura durumu	Panelde
InvoiceCreated, InvoicePending (her onay), InvoicePaymentCreated	beklemede
InvoicePaid (zincirde onaylandı, bakiyeye henüz geçmedi)	beklemede, not: "bakiyeye aktarılıyor"
InvoiceCompleted / durum completed	tamamlandı, bakiye yüklendi
InvoiceCancelled	başarısız
InvoiceTimedOut (60 dk içinde onaylanmadı)	süresi doldu

Eksik ödeme CoinPayments'ta ayrı bir son durum değildir: fatura tamamlanmaz, süre dolunca timedOut olur ve CoinPayments gönderilen tutarı müşteriye iade akışına alır (e-posta ile talep bağlantısı). Fazla ödemede fatura tamamlanır, fazlası müşteriye iade edilir.

Para birimleri

Fatura panelinizin para biriminde açılır; CoinPayments 49 fiat birimi tanır (TRY, USD, EUR, GBP, RUB, …). Sürücü kodu CoinPayments'ın sayısal para birimi kimliğine kendisi çevirir (USD → 5057, TRY → 5166). Müşterinin ödeyeceği koin faturada sabitlenmez; CoinPayments'ın ödeme sayfasında müşteri seçer ve dashboard'da Payment Settings'te açık bıraktığınız koinler sunulur. Panel para birimi bir kripto kodu ise (ör. USDT) sürücü çalışmaz; CoinPayments token'ları zincir ekiyle (USDT.TRC20) adlandırır.

Sık sorunlar

• "CoinPayments credentials missing": client_id ya da secret_key boş. İkisi de entegrasyon ekranından alınır; hesap şifresi ya da eski API anahtarı değildir.
• 401 / imza hatası fatura açarken: Sandbox kutusu ile bilgilerin alındığı ortam uyuşmuyor (sandbox bilgisi canlıda, ya da hesap B/C örneğinde). Bilgiler örnekler arasında geçmez.
• Ödeme yapıldı, bakiye yok: Admin → Ödemeler'de kaydın notuna bakın. InvoicePaid geldi, completed gelmediyse fon henüz CoinPayments bakiyenize geçmemiştir; dashboard'daki payout ayarına göre birkaç dakika sürebilir. Hiç webhook gelmediyse alan adının SSL'i ve callback adresinin https:// ile başladığı kontrol edilir.
• Webhook doğrulanmıyor: Dashboard'a elle eklenen webhook adresi paneldekinden farklı yazılmış (sondaki /, www.); adresi birebir eşleyin.
• Onaylanmamış ödeme "beklemede" kalıyor: Zincir onayı bekleniyor; CoinPayments her onayda webhook gönderir, notta x/y onay yazar.