TKPAY Sağlayıcısı
TKPAY, FinansZ'ye eklenen ödeme sağlayıcılarından biridir. Diğer sağlayıcılardan farklı olarak kimlik doğrulaması OAuth2 ile yapılır ve her istek ayrıca SHA-512 imza (hash) taşır. Terminal oluşturma adımları tüm sağlayıcılarda ortaktır; bu sayfa yalnızca TKPAY'e özel alanları ve kısıtları anlatır.
Terminalin nasıl oluşturulduğu: Terminal Oluşturma
Kimlik Bilgileri
Terminal oluştururken sağlayıcı olarak TKPAY seçildiğinde aşağıdaki alanlar istenir. Değerlerin tamamı TKPAY tarafından üye işyerine verilir.
| Alan | Zorunlu | Açıklama |
|---|---|---|
| İstemci Kimliği | Evet | OAuth2 client_id — jeton (token) alınırken kullanılır |
| İstemci Gizli Anahtarı | Evet | OAuth2 client_secret |
| Kullanıcı Adı | Evet | Ödeme isteklerindeki API kullanıcısı |
| Şifre | Evet | API kullanıcısının şifresi |
| Mağaza Anahtarı | Evet | İsteklerin imzasının (hash) üretildiği gizli anahtar |
| Üye İşyeri ID | Evet | TKPAY üye işyeri numarası |
| Varsayılan Müşteri E-postası | Hayır | Ödeme isteğinde müşteri e-postası gelmezse kullanılır |
| Varsayılan Müşteri Telefonu | Hayır | Ödeme isteğinde müşteri telefonu gelmezse kullanılır |
TKPAY; müşteri e-postası ve telefonunu ödeme isteğinde zorunlu tutar. Dijital POS, ödeme linki ve checkout akışlarında bu bilgiler müşteriden veya kayıttan alınır; hiçbiri yoksa yukarıdaki terminal varsayılanları gönderilir.
Gizli anahtarlar (istemci gizli anahtarı, şifre, mağaza anahtarı) yalnızca terminal kaydında saklanır ve ekranda maskeli gösterilir. Bu değerleri e-posta, ekran görüntüsü veya paylaşılan dokümanlarla iletmeyin.
Desteklenen İşlemler
| İşlem | Durum | Not |
|---|---|---|
| Güvenli ödeme (3D Secure) | ✅ | Banka doğrulama ekranı HTML veya yönlendirme olarak açılır |
| Güvensiz ödeme (2D) | ✅ | Tek adımda satış |
| Taksitli satış | ✅ | Taksit seçenekleri sorgulanabilir |
| Taksit sorgulama | ✅ | Kart bilgisi de aynı yanıttan gelir |
| BIN sorgulama | ✅ | Ayrı bir BIN servisi yok; kart bilgisi taksit sorgusu üzerinden sabit 1,00 TL tutarla alınır |
| İptal | ✅ | Yalnız işlemin yapıldığı gün (Türkiye takvimi) ve gün sonu alınmadan önce; işlemin tamamı |
| İade | ✅ | Kısmi iade desteklenir; gün sonu alınmış işlemler iptal edilemez, iade edilir |
| Ödeme sorgulama / mutabakat | ✅ | Sonucu belirsiz kalan işlemler otomatik toparlanır |
| Ön provizyon (PreAuth / PostAuth) | ❌ | TKPAY dokümanında böyle bir uç yok (yol haritasında) |
| 3D + ön provizyon | ❌ | Ön provizyon desteklenmediği için kapalı |
| Tekrarlayan ödeme (abonelik) | ❌ | TKPAY kart saklama / tekrarlayan ödeme desteklemiyor; dijital POS bu seçeneği TKPAY terminalinde göstermez |
| Gün sonu (batch close) | ❌ | TKPAY tarafında yapılır |
| Puan sorgulama | ❌ | Desteklenmiyor |
Bu yetenekler POS → Ayarlar → Terminal Sağlayıcı Ayarları ekranından da görüntülenebilir. Desteklenmeyen bir işlem denendiğinde sistem ödemeyi başlatmadan anlamlı bir hata döndürür.
3D Secure Akışı
- Ödeme başlatılır, TKPAY banka doğrulama adımını döndürür.
- Yanıt bir HTML formu ya da bir yönlendirme adresi olabilir; FinansZ hangisi geldiyse onu kullanır, ikisi birden gelirse tek bir yol seçilir.
- Müşteri doğrulamayı tamamlayınca TKPAY dönüş adresimize (
.../3ds/callback/tkpay/successveya.../fail) geri gönderir. - Dönüş imza taşıyorsa imza doğrulanır; imza tutmazsa işlem finansallaştırılmaz. Dönüş imza taşımıyorsa sonuç tarayıcıdan gelen bilgiye değil, TKPAY'e yapılan ödeme sorgusuna göre belirlenir: yalnız TKPAY'in tam doğrulanmış olarak kaydettiği işlem tamamlanır.
- Doğrulama tam değilse (yarım doğrulama) işlem güvenlik gereği tamamlanmaz.
- Aynı işlem için dönüş iki kez gelirse (tarayıcı yenilemesi) kart ikinci kez çekilmez.
Müşteri tarayıcısını doğrulama ekranında kapatırsa kayıt beklemede kalır; arka planda çalışan mutabakat işi bu kayıtları TKPAY'e sorarak sonuçlandırır.
Bilinen Kısıtlar
- TKPAY'in kendi ödeme sayfası (hosted form) kullanılmıyor. Kart bilgileri FinansZ ekranlarından alınır; TKPAY'in barındırdığı ödeme formu bu entegrasyonun kapsamı dışındadır.
- Ön provizyon yoktur. Ön provizyon gerektiren senaryolarda başka bir terminal seçilmelidir.
- Sipariş numarası en fazla 20 karakterdir ve yalnız harf, rakam ve tire içerebilir. TKPAY terminalleri için sistem kısa bir sipariş numarası üretir; iptal, iade ve sorgulama bu numara üzerinden çalışır.
- Gün sonu alınmış işlem iptal edilemez. İptal denemesi "iade işlemini kullanın" uyarısıyla reddedilir; ödeme durumu değişmez, iade ekranından iade yapılır.
- Tekrarlayan ödeme yoktur. Abonelik gerektiren senaryolarda başka bir terminal seçilmelidir.
- Sabit çıkış IP'si zorunludur. TKPAY isteklerimizi yalnızca bildirilen IP adresinden kabul eder (aşağıya bakın).
Altyapı Gereksinimleri
Bu ayarlar sistem yöneticisi tarafından ortam bazında yapılandırılır; son kullanıcı ekranında yer almaz.
| Ayar | Açıklama |
|---|---|
Dönüş adresi (CallbackUrls:Tkpay) | 3D doğrulaması sonrası TKPAY'in geri döneceği adres |
Üye işyeri IP'si (Payment:MerchantIpAddress) | Servisin dışa çıkış (NAT/egress) IP adresi; TKPAY'e bildirilen adresle aynı olmalıdır. Boş bırakılırsa TKPAY isteği reddeder |
TKPAY adresleri (Settings:PosService.Terminals.Tkpay.BaseUrl / .AuthUrl) | Sandbox ve üretim adresleri farklıdır (üretim: merchant.api.tkpay.com ve auth-prod.api.tkpay.com). Dağıtım yapılandırmasından verilir; POS → Ayarlar → Terminal Sağlayıcı Ayarları ekranı etkin değeri gösterir ve gerekirse üzerine yazar. Boşsa kodun sandbox varsayılanı geçerlidir |
Gateway sağlayıcı kimliği (Settings:PosService.Terminals.Tkpay.VendorId) | TKPAY'in entegratöre verdiği vendorId; tüm terminallerde ortaktır, aynı ekrandan da girilebilir. Boşsa isteklerde gönderilmez |
Üretime geçmeden önce TKPAY adreslerinin sandbox'tan üretim adresleriyle değiştirildiğini,
vendorId'nin girildiğini ve üretim çıkış IP'sinin TKPAY'e bildirildiğini doğrulayın.
Test Ortamı
TKPAY sandbox ortamında test kartları, son kullanma tarihleri, CVV ve 3D şifreleriyle birlikte TKPAY entegrasyon dokümanında listelenir (8 banka kartı + 4 hatalı kart senaryosu). Test kartları güvenlik gereği bu sayfada yayımlanmaz; güncel liste için TKPAY entegrasyon dokümanına veya TKPAY destek ekibine başvurun.
Sık Karşılaşılan Hatalar
| Belirti | Olası sebep |
|---|---|
| İstek imza hatasıyla dönüyor | Mağaza anahtarı yanlış girilmiş olabilir |
| Zaman damgası hatası | Sunucu saati TKPAY'in kabul ettiği ±10 dakikalık aralığın dışında |
| "Bu kart için bankanın ek doğrulaması gerekiyor" | TKPAY bu kart için 3D Secure zorunlu tuttu; ödemeyi 3D ile tekrarlayın |
| Tüm istekler reddediliyor | Çıkış IP'miz TKPAY'de tanımlı olmayabilir |
| "Ödeme dönüşünün imzası doğrulanamadı" | 3D dönüşünün imzası tutmadı; işlem bilerek tamamlanmaz |
| "3D doğrulaması sağlayıcı tarafında teyit edilemedi" | İmzasız 3D dönüşü TKPAY'in ödeme sorgusuyla teyit edilemedi; kart çekilmemiştir, ödeme yeniden denenebilir |
| "Bu işlemin gün sonu alınmış; iptal yerine iade işlemini kullanın" | Gün sonu geçmiş işlem iptal edilemez; iade yapın |
| "Bu ödeme sağlayıcısı tekrarlayan ödemeyi desteklemiyor" | TKPAY terminalinde abonelik başlatılamaz; başka terminal seçin |
Hata kodlarının tam listesi TKPAY entegrasyon dokümanındadır.