Poyra bankalarla protokol üzerinden konuşur: NestPay bir bankanın değil, onlarca bankanın kullandığı bir altyapının adıdır. Aynı desen ödeme kuruluşlarında da geçerlidir — CCPayment tek konnektördür ama arkasında yedi marka vardır. POS hesabı eklerken protokolü seçer, kendi üye işyeri kimliklerinizi girersiniz; kimlikler AES-256-GCM ile şifrelenir ve panelden bir daha okunamaz (yalnız değiştirilir).
POS bağlantıları ekranı: dinamik kimlik formu ve hesap sağlığı

POS Bağlantıları — kimlik alanları seçilen protokolün kataloğundan üretilir

​
Kartın nerede girildiği her şeyi belirler

Envantere bakmadan önce tek bir ayrımı oturtmak gerekir, çünkü PCI kapsamınızı, dönüşüm oranınızı ve hangi hesabın hangi akışta aday olacağını bu belirler:

Banka-hosted (hosted)

Kart bankanın sayfasında girilir. PCI kapsamı minimaldir — kart verisi Poyra’ya hiç uğramaz. Varsayılan ve önerilen akış budur.

3DS'li direct

Kart sizin/Poyra’nın formunda toplanır, doğrulama bankada yapılır. Ödeme sayfası sizde kalır (dönüşüm yüksek) ama PCI kapsamına girersiniz.
Hosted akışta 3DS’li direct’ten başka seçeneği olmayan hesaplar rota adayı listesinden otomatik düşer — kart girilemeyecek bir POS’a yönlendirme yapılmaz. Tersi de doğrudur: confirm-direct çağrısı yalnız direct destekleyen hesaplara gider.

​
Adaptör envanteri

​
Banka sanal POS’ları

​
Ödeme kuruluşları (yurt içi)

​
E-ihracat ve test

Tablodaki boşluklar bilinçlidir:
  • Posnet, İyzico, Payten, CCPayment, Moka, Tami, ParamPos, AHL Pay ve PayTR banka-hosted kart girişi sunmaz — bu platformlarda kart işyeri tarafında toplanır. Adaptör “desteklemiyor” der ve hosted rotada hesap atlanır; sessizce yanlış bir akışa düşülmez.
  • PayTR’da ayrı bir iptal ucu yoktur. Void çağrısı poyra.not_supported döner ve gün içi işlem de iade ucundan geçer. Craftgate’te durum tersidir: ayrı iptal ucu yoktur ama iade ucu gün içi işlemde kendiliğinden CANCEL üretir.
  • Stripe ve Adyen Türk banka taksidini bilmez; taksitli işlem bu hesaplara hiç yönlendirilmez — aksi hâlde tutar tek çekim alınır ve vade farkı sessizce kaybolurdu.
Kataloğu çalışan sisteminizden GET /v1/connectors/catalog ile, “benim kurulumum bugün ne yapabilir” sorusunu GET /v1/platform/capabilities ile alırsınız. Katalog kimlik alanlarını da taşır — paneldeki POS ekleme formu bu şemadan üretilir, bu yüzden yeni bir konnektör eklendiğinde panelde elle form yazılması gerekmez.

​
Sertifikasyon durumu

Banka dokümanı yerine protokolün genel deseninden yazılmış adaptörler katalogda, görünen adının sonunda “SERTİFİKASYON BEKLİYOR” ibaresi taşır; koddaki karşılıkları TODO(cert) işaretleridir.
Şu an sertifikasyon bekleyenler: intervpos · kuveytturk · vakifkatilim · payfor · iyzico · moka · payten · ccpayment · paynkolay · tami · ahlpay · parampos · paytr · craftgate · lidio.Bu adaptörlerin akışı, tutar biçimi, hash yapısı ve hata eşlemesi kurulu ve testlidir — ama alan adları, imza sırası ve durum kodları sağlayıcının kendi dokümanı ve sertifikasyon ortamıyla doğrulanmadan üretim trafiği açılmamalıdır. gvp, payflex, posnet ve nestpay de sandbox doğrulaması bekleyen TODO(cert) maddeleri taşır. Canlıya çıkış listesindeki “banka sertifikasyonları tamamlandı” maddesi tam olarak budur.
stripe ve adyen sertifikasyon gerektirmez (kamuya açık, sürümlü satıcı API’si); mockbank canlıya hiç çıkmaz.

​
Ortak adaptör sözleşmesi

Her adaptör aynı arayüzü uygular; ödeme çekirdeği bankaya özgü hiçbir şey bilmez: Banka hata kodları birleşik sözlüğe eşlenir; ham kod her zaman yanında taşınır.

​
Konnektör uyum kiti

Sözleşmenin tutulduğunu tek tek konnektör testleri değil, ortak bir uyum kiti kanıtlar. Kit konnektör listesini DI kaydından okur: yeni bir banka eklendiğinde teorilerin verisi kendiliğinden büyür, kimsenin test yazması gerekmez. Her konnektör için zorunlu olan beş madde:
  1. Kayıtlı her konnektör katalogda görünür. Bu kural somut bir arızayı yakaladı: InterVPOS ve Kuveyt Türk DI’a kayıtlıydı ama katalog anahtar listesinde yoktu — panelin “POS bağlantısı ekle” ekranında iki banka hiç görünmüyordu.
  2. Tanımlayıcı tutarlıdır — anahtar, görünen ad ve yetenek beyanı birbirini tutar.
  3. Eksik kimlik alanı yapılandırma hatası atar, sessizce yarım istek gitmez.
  4. Boş ya da kurcalanmış dönüş kabul edilmez (aşağıya bakın).
  5. Tarayıcıya giden formda sır bulunmaz — mağaza anahtarı, API şifresi ya da imza sırrı müşterinin göreceği alanlara sızmaz.
  6. Banka erişilemezse yük devretmeye uygun hata doğar, terminal red değil.
Kit ilk koşuşunda 46 vakadan 8’ini kırdı. En ciddi bulgu güvenlikti: imzasız callback kabul ediliyordu. InterVPOS’ta denetim “hash var ama tutmuyorsa reddet” biçimindeydi — Hash alanı hiç gönderilmezse doğrulama tamamen atlanıyordu. Kuveyt Türk’te ise hiç imza doğrulaması yoktu. Callback adresi tek kullanımlık 256 bit belirteç taşıdığı için rastgele biri erişemiyordu, ama ödemeyi yapan müşteri o adresi kendi tarayıcısında görüyordu: bankaya hiç para göndermeden siparişini ödenmiş gösterebilirdi. Artık imzanın yokluğu da reddedilir (fail closed), Kuveyt Türk/Vakıf Katılım ailesinde ise tarayıcı dönüşü tek başına asla başarı sayılmaz — tahsilat ThreeDModelProvisionGate sunucu teyidiyle kesinleşir.

​
Protokol notları

Konnektör seçerken bilinmesi gereken, davranışı gerçekten değiştiren farklar:
Dönüşteki imza tutar bilgisini de kapsıyorsa ayrı bir sunucu çağrısına gerek yoktur: NestPay, GVP, InterVPOS, PayFor (ResponseHash) ve PayNKolay (hashDataV2 — imza tutarı kapsar) böyledir. PayNKolay’da başarı kodu 2’dir, "00" değil; bu tür sürprizler adaptörde emilir.
PayFlex (Ptkn ile sonuç servisi), Posnet (OOS üçlemesi), Kuveyt Türk / Vakıf Katılım (ThreeDModelProvisionGate), CCPayment (/payment/complete), İyzico (/payment/3dsecure/auth), Moka (GetDealerPaymentTrxDetailList), Payten (QUERYTRANSACTION), Tami (/payment/query), ParamPos (TP_WMD_Pay), AHL Pay (PaymentInquiry), Craftgate, Lidio (hosted: GetHostedPaymentStatus, direct: FinishPaymentProcess), Stripe ve Adyen.Bu ailede tarayıcıdan gelen alan — imzası geçerli olsa bile — tahsilat kanıtı sayılmaz. PayTR üçüncü bir yoldadır: sonuç, imzalı bir sunucu bildirimi olarak gelir ve bildirim ucunun düz metin OK döndürmesi gerekir, yoksa PayTR göndermeyi tekrarlar.
Yedi markanın kullandığı bu platformda hash_key bir SHA özeti değil, AES-256-CBC ile geri çözülebilir bir şifredir. Doğrulama “yeniden üret ve eşitle” değil, “çöz ve içine bak” biçimindedir. Testler gidiş-dönüş tutarlılığını, yanlış sırla çözülememeyi ve başka bir işlemin imzasının taşınamamasını sabitler.
Poyra içeride parayı her zaman kuruş cinsinden long taşır; çeviri adaptörün işidir. GVP, Kuveyt Türk, Vakıf Katılım ve PayTR kuruş bekler; ParamPos virgüllü ondalık ister (149,90); Stripe/Adyen sıfır ve üç ondalıklı para birimlerini ayrıca çevirir. Yanlış biçim, yüz kat fazla ya da yüz kat eksik çekim demektir — bu yüzden her biri birim testle sabitlenmiştir.
CCPayment (7 marka), Payten/MSU (3 marka), NestPay (12 banka) ve BOA (Kuveyt Türk + Vakıf Katılım) tek adaptörle çözülür; marka seçimi hesabın gateway_base kimlik alanıyla yapılır. Her marka için ayrı adaptör yazmak, aynı hatayı yedi yerde düzeltmek olurdu.BOA ailesinde fark yalnız XML kök elemanı ve gateway yolu önekindedir; akış, hash yapısı ve provizyon teyidi ortaktır.

​
Hesap sağlığı ve canary

On dakikada bir çalışan canary işi, tüm aktif hesapları yoklar ve sağlığı healthy / degraded / down olarak günceller. down hesap rota kararında otomatik atlanır; sağlık değişimi panelin canlı akışına uyarı düşürür (“İş POS erişilemiyor — trafik diğer POS’lara yönlendiriliyor”). Panelden “Test et” düğmesi aynı yoklamayı anında çalıştırır. Yoklama ucu her protokolde yoktur: canary şu an nestpay, posnet, stripe, adyen ve mockbank hesaplarında sağlık yazar. Diğerlerinde sağlık, işlem sonuçlarından ve elle yapılan değişikliklerden yönetilir — uydurma bir yoklama çağrısı, olmayan bir güvence verirdi. Hesap yönetimi API’den de yapılır: POST /v1/connector-accounts (ekleme), …/{id}/settings (etiket, öncelik, test/canlı modu), …/{id}/credentials (kimlik yenileme), …/{id}/status (devre dışı bırakma — hesap silinmez), …/{id}/probe (anında yoklama).