Checkout.com

Gereken bilgiler

Checkout.com Dashboard'da:

• secret_key: Developers → API keys: gizli anahtar (sk_sbox_… sandbox, sk_… canlı).
• client_id: Settings → Account structure sekmesinin sağ üst köşesindeki cli_… değeri. Checkout.com her hesaba özel bir API adresi verir (https://<önek>.api.checkout.com); önek bu kimliğin cli_ sonrası ilk sekiz karakteridir ve panel bunu kendisi türetir. Öneki doğrudan da girebilirsiniz (Developers → Overview'da görünen adresteki alt alan adı). Boş bırakılırsa panel öneksiz api.checkout.com adresini dener.
• webhook_secret: webhook yapılandırmasında ürettiğiniz signature key (aşağıya bakın).

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

Sandbox: sandbox hesabının sk_sbox_… anahtarını ve sandbox client_id'sini girin, sandbox (test) modu kutusunu işaretleyin; panel <önek>.api.sandbox.checkout.com'a bağlanır. Canlı ve sandbox ortamlarının client_id'si farklıdır.

Hosted Payments Page hesabınızda açık olmalıdır; Checkout.com bunun için solution engineer'ınıza ya da destek ekibine başvurmanızı ister.

Webhook (zorunlu)

Bakiye yalnız Checkout.com'un sunucudan sunucuya gönderdiği webhook ile yüklenir; müşterinin tarayıcı dönüşü hiçbir şeyi kredilendirmez. Bu yüzden webhook Checkout.com tarafında mutlaka kurulmalıdır:

1. Dashboard → Developers → Webhooks → Create configuration.
2. Endpoint URL:

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

1. Signature key için Generate key'e basın; çıkan değeri panele webhook_secret olarak girin. (Authorization header key panel tarafından kontrol edilmez, üretmeniz gerekmez.)
2. Şu olay türlerini işaretleyin: payment_captured, payment_approved, payment_declined, payment_capture_declined, payment_pending, payment_expired, payment_canceled.
3. Sandbox ve canlı ortamda ayrı ayrı yapın; anahtarlar ortama özeldir.

Panel her webhook'un Cko-Signature başlığını, ham gövdenin webhook_secret ile HMAC-SHA256 (hex) özetiyle karşılaştırır; uyuşmayan istek 400 ile reddedilir. Doğrulanan her istek 10 saniye içinde 200 ile yanıtlanır.

Akış

1. Müşteri tutarı girer, Checkout.com'u seçer. Telefon numarası istenmez.
2. Panel POST /hosted-payments ile bir oturum açar: tutar en küçük birimde (250,00 TRY → 25000), reference bizim ödeme numaramız, capture: true (onaylanan tutar hemen tahsil edilir), customer_retry.max_attempts: 0 (reddedilen deneme oturumu bitirir). Müşteri pay.checkout.com'daki sayfaya yönlendirilir; kart bilgisi ve 3D Secure orada.
3. Ödeme bitince müşteri success_url / failure_url / cancel_url ile panelin /payments/checkout_com/return adresine döner; bu sayfa yalnız "Bakiye yükle"ye yönlendirir.
4. Checkout.com webhook'u gönderir. payment_captured gelince ödeme tamamlanır ve bakiye yüklenir (data.amount en küçük birimden çevrilerek kaydedilir). Aynı evt_… numarası ikinci kez gelirse yok sayılır; bakiye iki kez yüklenmez.
5. Webhook'lar sırasız gelebilir; payment_approved payment_captured'dan sonra gelirse zaten tamamlanmış ödemeye dokunmaz.

Durumlar

Olay	Paneldeki sonuç
payment_captured	tamamlandı, bakiye yüklendi
payment_approved, payment_pending	beklemede (tahsilat / yönlendirme bekleniyor)
payment_declined, payment_capture_declined	başarısız; response_summary ödeme notuna yazılır
payment_canceled	başarısız (müşteri iptal etti)
payment_expired	süresi doldu
diğer olaylar (payment_refunded, payment_voided…)	açık ödemeyi beklemede bırakır, tamamlanmış ödemeye dokunmaz

Para birimleri

Panelinizin para birimi Checkout.com hesabınızın işlem yapabildiği bir birim olmalı (TRY dahil). Tutar çevrimi Checkout.com'un kuralına göredir: JPY, KRW, ISK, VND gibi birimler tam sayı; BHD, KWD, OMR, JOD, TND, IQD, LYD 1000'e; diğer her birim 100'e bölünür.

Fatura ülkesi

Checkout.com billing.address.country alanını zorunlu tutar, panel ise müşterinin ülkesini bilmez. Panel önce yöntemin extra.billing_country değerine (iki harfli ülke kodu) bakar; yoksa panel para biriminin ülkesini (TRY → TR, USD → US, EUR → DE…) gönderir. Bu alan risk kurallarını etkileyebilir; hedef ülkeniz farklıysa doldurun.

Sık sorunlar

• "Ödeme başlatılamadı: HTTP 401": anahtar ortamı yanlış (sk_sbox_… canlıda ya da tersi) veya client_id öneki yanlış hesaba ait.
• Ödeme başarılı ama bakiye yok: webhook yapılandırması eksik ya da webhook_secret başka bir yapılandırmanın anahtarı. Dashboard → Developers → Webhooks'ta teslimat kaydına bakın; panel 400 döndüyse imza uyuşmuyordur. Checkout.com başarısız webhook'u sekiz kez yeniden dener.
• Ödeme "beklemede" kaldı: yalnız payment_approved geldi, payment_captured seçili değil. Olay türlerini kontrol edin; capture gelince ödeme kendiliğinden tamamlanır.
• billing_address_country_required / currency_invalid: hesabınızın işlem kanalı o para birimini desteklemiyor; Checkout.com'a danışın.
• Sandbox'ta kart reddediliyor: Checkout.com'un test kartlarını kullanın; gerçek kart sandbox'ta çalışmaz.