`param` — Param Pos (TurkPos / Doruk Yazılım)

> Tip: Ödeme kuruluşu (PSP) — TurkPos ürünü, BDDK lisanslı > Adapter'lar: InvumPosGatewayParam* > Son senkron: 2026-05-04 (Hafta 14 — dev portal spec review + Tutar dot fix + Dekont_ID kaldırma; sandbox akışı henüz tam doğrulanmadı) > Last-known-good API: TurkPos SOAP service_turkpos_prod.asmx (2026-Q2 dev portal)

Param SOAP/WSDL kullanıyor — REST/JSON yok. PHP SoapClient ile çalışıyoruz; her response <Method>Result ile sarılı (extract gerekli). Türk PG ekosisteminin SOAP kalanı (PayTR/iyzico REST'e geçti, Param hâlâ SOAP'ta).

Önemli WSDL tutarsızlığı: Refund (ParamGateway adapter) testposws host'unu kullanıyor; pending order status query (ParamStatusQuery) test-pos host'unu kullanıyor (Hafta 7 vs Hafta 12 farkı). Aynı çağrı 2 farklı endpoint'e gidiyor — sandbox'ta ikisi de cevap veriyor ama production'da hangisinin olacağı belirsiz. Faz 1.5 backlog: standardize.

1. Bağlantı bilgileri

Dev portal: https://dev.param.com.tr/tr/api (resmî dokümantasyon) Live ASMX (her method için): <base>/turkpos.ws/service_turkpos_prod.asmx?op=<MethodName> — browser'da .NET'in ürettiği test sayfası Mailing list: Yok; duyurular merchant panel + email Yetkili temsilci: TODO (production sözleşmesi sırasında atanır; Doruk Yazılım kontağı) Destek email: destek@param.com.tr

Sandbox test credentials (dev portaldan):

CLIENT_CODE     = 42469
CLIENT_USERNAME = TP10045106
CLIENT_PASSWORD = C8B664272E80421F
GUID            = A65D9C12-5B27-463C-902C-B808D95B5989

2. Auth şeması — SOAP `G` envelope + GUID

Param her method'a iki şekilde auth koyuyor:

G struct (her request'te ilk parametre):

“ G: CLIENT_CODE: string (5 hane) CLIENT_USERNAME: string (TP-prefix) CLIENT_PASSWORD: string (16 hane hex) “

GUID (üst-seviye field, her request'te) — merchant'a özel UUID

Her ikisi de plain text SOAP envelope içinde geçiyor; HMAC/imza yok. TLS güvenliğine bağımlı. Replay protection yok (request'te timestamp veya nonce yok).

Sırlar (encrypted store): client_code, client_username, client_password, guid. WCGateway encrypted; RefundService::bootstrap decrypt ediyor.

3. Endpoint tablosu (TurkPos SOAP method'ları)

Sonuc semantiği (kritik):

Sonuc > 0 → başarı; ID/sayı bilgisi taşır
Sonuc = 0 → "kayıt bulunamadı" — refund'da olmamalı (failed yorumlanır)
Sonuc < 0 → hata; Sonuc_Str Türkçe açıklama taşır

Durum router (refund):

Aynı gün (transaction.created_at == now() günü) → IPTAL (henüz hesaplaşmamış, money never settles)
Önceki gün → IADE (post-settlement, refund clearing window)
ParamRefund::resolve_durum() saatlik karşılaştırma değil calendar-day karşılaştırması yapıyor (WP timezone bazlı)

Tutar formatı:

Charge (TP_WMD_UCD): Islem_Tutar formatı 100,00 (virgül) — TR locale
Refund (TP_Islem_Iptal_Iade_Kismi4): Tutar formatı 100.00 (dot) — Hafta 14 dev portal review'unda doğrulandı; eskiden virgül atıyorduk, sandbox sessizce reddediyordu

Test kartları: Param sandbox dokümantasyonunda listelenir; bizde henüz manuel test yapılmadı. TODO: ilk başarılı sandbox test'inden sonra buraya yaz.

4. Bilinen quirk'ler

#1 — `Tutar` virgül vs dot tutarsızlığı (Hafta 14'te düzeltildi)

Davranış: TP_Islem_Iptal_Iade_Kismi4 request'te Tutar virgül ile gönderirsen Param sessizce reddediyor (Sonuc = -1, Sonuc_Str genelde generic).

Kök neden: SOAP servis decimal parsing'i invariant culture (dot) bekliyor. Charge endpoint'i (TP_WMD_UCD) Islem_Tutar virgül kabul ediyor — alan/method bazlı format farkı.

Çözüm: ParamRefund::format_amount() Hafta 14'te dot'a çevrildi (number_format(amount, 2, '.', '')).

#2 — `Dekont_ID` Kismi4 request'te yok

Davranış: Eskiden TP_Islem_Iptal_Iade_Kismi4 request'ine Dekont_ID alanı koyuyorduk; dev portal review'unda fark edildi — bu method'un input listesinde Dekont_ID YOK.

Kök neden: Param refund'u Siparis_ID üzerinden eşleştiriyor (charge sırasında gönderdiğimiz WC order_id). Dekont_ID sadece response'ta var (Iade_Dekont_ID adıyla — yeni iade ref'i).

Çözüm: Hafta 14'te Dekont_ID request'ten kaldırıldı, Siparis_ID = transaction_row['order_id'] set edildi. Response anahtarı Iade_Dekont_ID öncelikli, eski Dekont_ID fallback.

#3 — WSDL host tutarsızlığı (`testposws` vs `test-pos`)

Davranış: İki sandbox WSDL host'u var, bizim kodda farklı yerlerde farklı kullanılıyor — ParamGateway ve ParamRefund testposws.param.com.tr, ParamStatusQuery test-pos.param.com.tr.

Kök neden: Hafta 7 (charge/refund) ve Hafta 12 (status query) farklı zamanlarda yazıldı, dev portal o sıralarda farklı host gösteriyordu.

Çözüm (Faz 1.5): Standardize — testposws.param.com.tr ana yola çek (charge/refund/status hepsi aynı host'tan). Production'da sorun çıkmaması için sözleşme aşamasında muhabir Doruk temsilcisine sor.

#4 — `Sonuc = 0` belirsiz durum

Sonuc = 0 Param'da "kayıt bulunamadı" demek. Refund'da olmamalı çünkü Siparis_ID geçerli bir charge'ın olduğunu varsayıyor; ama olası bir durum: charge başarısız olmuş, callback hata almış, transaction tablosuna yazılmış ama Param tarafında ödeme oluşmamış. Bu durumda refund Sonuc=0 döner; biz "failed" diye yorumluyoruz (Sonuc>0 sadece başarı).

#5 — SOAP fault → pending

SoapFault exception'ı (network timeout, WSDL parse fail) RefundResult::pending olarak yorumlanıyor — manuel reverify endpoint'ine bırakılır. Sonuç bilinmediği için failed deyip retry'a tetiklemekten daha güvenli.

#6 — `cache_wsdl` flag (üretimde kritik)

PHP SoapClient WSDL'i her request'te indiriyor — production'da Param sunucularına dakikada yüzlerce WSDL fetch atmak istemiyorsun. WSDL_CACHE_BOTH flag'i ile lokal cache açılıyor (/tmp/wsdl-* dosyaları). PHP-FPM restart olmadığı sürece cache canlı kalıyor.

5. Bizim implementasyon notları

WCGateway: ParamWCGateway — slug invum_pos_param. Encrypted:

client_code, client_username, client_password, guid.

Charge + callback finalize + status: ParamGateway

– charge() → TP_WMD_UCD → 3DS bank form HTML / redirect URL döndürür – validate3DCallback($_POST) → TP_WMD_Pay → finalize – getStatus($order_id) → TP_Islem_Sorgulama4

Refund: ParamRefund (RefundInterface) — TP_Islem_Iptal_Iade_Kismi4
StatusQuery: ParamStatusQuery (StatusQueryInterface) — pending order

cron için (farklı WSDL host'u, bkz. quirk #3)

Callback REST endpoint: POST /wp-json/invum-pos/v1/param/callback,

ParamCallbackController. Param 3DS sonrası browser üzerinden form-POST yapıyor (iyzico gibi).

SHA2B64: Sha2B64 helper sınıfı — Param'ın bazı endpoint'lerinde

kullanılan SHA2+base64 imza şeması (charge esnasında kart bilgisi hashleniyor).

Persist edilen field'lar (wp_invum_pos_transactions):

transaction_id = Param Dekont_ID (callback'te dönen)
payment_transaction_id = boş (Param'da iyzico gibi per-item ID

yok; refund Siparis_ID üzerinden gidiyor)

raw_response = TP_WMD_Pay yanıtı, masked

Faz 1.5+ backlog:

WSDL host standardize
Türk Lirası dışı currency (USD/EUR) — Param dev portalında var, biz

desteklemiyoruz

TP_Islem_Iade_Toplu (toplu iade) endpoint'i — bulk refund senaryosu

6. Test connection (Pro modülü)

CredentialPresenceTest ne kontrol ediyor:

4 alan da boş mu (presence)

Eksik (Faz 2): TP_Test_Baglanti benzeri bir auth-only ping endpoint'i Param'da var mı dev portal'dan bakılacak; varsa gerçek auth test'i yapılacak.

7. Saved Cards / KS_* (Hafta 15 — uygulandı)

> Durum (2026-05-05): F6-1/F6-2/F6-3/F6-4 commit zinciri shipped. > ParamCardVault (KS_Kart_Ekle / KS_Tahsilat / KS_Kart_Sil) + > ParamGateway vault delegasyonu + ParamWCGateway 3-branch dispatch > (saved-card / fresh+save / fresh) + ParamCallbackController > TURKPOS_RETVAL_* callback shape handling. Standalone "Yeni Kart Ekle" > akışı AccountHook üzerinden Param için açık. > Sandbox doğrulaması: Param IP whitelist mail cevabı bekleniyor — > kod yolu unit-test seviyesinde tamamen yeşil, A4 bloğu gelir gelmez E2E > tek seferde geçecek. > **KS_* WSDL ayrımı: KS_Kart_Ekle / KS_Tahsilat / KS_Kart_Sil > ayrı bir WSDL endpoint'inde yaşıyor: /out.ws/service_ks.asmx > (vs charge'ın kullandığı /turkpos.ws/service_turkpos_prod.asmx), > namespace'i de farklı (turkpara.com.tr vs turkpos.com.tr). Üretimde > bu ayrımı gurmepos-pro v6 doğruladı. > Auth:** Aynı G struct + body GUID — yeni sır gerekmez.

7.1. Token modeli

KS_GUID — Param tarafından dönen per-card token. KS_Kart_Ekle

başarılı olduğunda response'da KS_GUID adıyla geliyor.

Per-user customer reference YOK — Param KS_* ailesi user-level

grouping yapmıyor (iyzico'nun cardUserKey'ine veya PayTR'ın utoken'ına benzer bir konsept yok). Biz wp_invum_pos_saved_cards.user_id üzerinden uygulama tarafında grupluyoruz.

7.2. SOAP endpoint ayrımı (KRİTİK)

Param'ın iki ayrı SOAP servisi var, charge ve saved-card metodları farklı endpoint'lere gidiyor:

Sandbox URL'ler:

https://testposws.param.com.tr/turkpos.ws/service_turkpos_prod.asmx (charge)
https://testposws.param.com.tr/out.ws/service_ks.asmx (saved cards)

Prod URL'ler:

https://posws.param.com.tr/turkpos.ws/service_turkpos_prod.asmx
https://posws.param.com.tr/out.ws/service_ks.asmx

7.3. SOAP method tablosu (KS_*)

Hash formülü (KS_Tahsilat için): aynı TP_WMD_UCD charge formülü — SHA2B64( CLIENT_CODE + GUID + Taksit + Islem_Tutar + Toplam_Tutar + Siparis_ID ) (TRY için). Param'ın kendi SHA2B64 SOAP method'undan hash üretiliyor (mevcut Sha2B64 helper sınıfımız ile).

KS_Kart_Ekle'nin kendi hash'i YOK — güvenlik G credentials + TLS'e bağlı.

7.4. Akış — Tokenize (vault a card)

İki yol:

A) Tokenize-during-charge (önerilen) — gerçek bir charge sırasında kartı kaydet. Önce KS_Kart_Ekle ile token al, sonra KS_Tahsilat ile o token'la ödeme yap.

1. WC Checkout: kullanıcı PAN/CVV/expiry girer + "Kartımı kaydet" işaretler
2. SOAP call (KS namespace, /out.ws/service_ks.asmx):
   KS_Kart_Ekle(G, GUID, KK_Sahibi, KK_No, KK_SK_Ay, KK_SK_Yil)
   ↳ CVV gönderilmez (KS_Kart_Ekle CVV istemiyor)
3. Sonuc=1 → response.KS_GUID alınır
4. SOAP call (KS namespace, /out.ws/service_ks.asmx):
   KS_Tahsilat(G, GUID, KS_GUID, Siparis_ID, Taksit, Islem_Tutar, Toplam_Tutar,
               Islem_Hash, KK_CVC, IPAdr, Hata_URL, Basarili_URL, Ref_URL)
   ↳ KK_CVC bu sefer gerekli (charge için)
5. Response: UCD_HTML 3DS challenge → tarayıcıda render → ACS doğrulama
6. Callback başarılı → wp_invum_pos_saved_cards INSERT:
   user_id, gateway='param', gateway_card_token=KS_GUID,
   masked_pan, brand, expiry_month, expiry_year
7. Raw PAN/CVV anında discard

B) Standalone "Kartlarım" sayfası — charge yapmadan kart ekle (My Account → Payment Methods).

1. Kart Ekle formu → KK_Sahibi, KK_No, KK_SK_Ay, KK_SK_Yil
2. SOAP call: KS_Kart_Ekle (CVV yok)
3. Sonuc=1 → KS_GUID döner → DB'ye yaz

Bu yol Param'ın KS_Kart_Ekle metodunun CVV istemiyor olmasından dolayı mümkün — iyzico ve PayTR'da yok. UX avantajı: charge öncesi kullanıcı "kartlarımı önceden kaydedeyim" diyebilir.

7.5. Akış — Charge with saved card

1. WC Checkout: kullanıcı "saklı karttan öde"
2. Vault tablosundan oku: KS_GUID (gateway_card_token)
3. Compute Islem_Hash (mevcut SHA2B64 helper; charge ile aynı formül)
4. SOAP call (KS namespace, /out.ws/service_ks.asmx):
   KS_Tahsilat(G, GUID, KS_GUID, Siparis_ID, Siparis_Aciklama,
               Taksit=1, Islem_Tutar/Toplam_Tutar (virgül format),
               KK_CVC (kullanıcıdan istenir — quirk #V4),
               Islem_Hash, Hata_URL, Basarili_URL, IPAdr, Ref_URL)
5. Response: UCD_HTML (auto-submit form) → tarayıcıda render → ACS challenge
6. Callback (Basarili_URL) → TP_Islem_Sorgulama4 ile final state al
   (KS_Tahsilat'ın TP_WMD_Pay finalize'ı yok — sorgu ile reconcile)
7. payment_complete + transactions tablosu update

7.6. Vault-specific quirk'ler

#V1 — `KS_*` ailesi farklı WSDL'de — auth namespace de farklı

İlk araştırmada service_turkpos_prod.asmx?op=KS_Kart_Ekle 404 döndüğü için "yok" sanılmıştı. Aslında ayrı bir endpoint (service_ks.asmx, out.ws path'inde) ve farklı XML namespace (turkpara.com.tr vs turkpos.com.tr) kullanıyor. SoapClient kullanırken her iki WSDL'i ayrı ayrı yüklemek lazım — tek WSDL ikisine de hizmet etmiyor.

Çözüm: ParamCardVault sınıfı kendi SoapClient'ını out.ws/service_ks.asmx?wsdl ile init eder; mevcut ParamGateway charge client'ı kullanmaya devam eder.

#V2 — KS_Tahsilat'ın TP_WMD_Pay benzeri finalize endpoint'i yok

Charge akışı TP_WMD_UCD (init) → TP_WMD_Pay (callback finalize) iken, saved-card akışı KS_Tahsilat (init+3DS) → callback geldikten sonra TP_Islem_Sorgulama4 ile manuel sorgulayıp state'i kapatma şeklinde. Çünkü KS_* namespace'inde "pay" eşdeğeri yok.

Çözüm: Saved-card callback handler KS_Tahsilat reference'ını (Siparis_ID) kullanarak TP_Islem_Sorgulama4 ile final state alır, buna göre payment_complete tetikler.

#V3 — KS_Kart_Ekle CVV istemiyor (avantaj)

Charge'tan farklı olarak KS_Kart_Ekle request'inde CVV alanı yok (KK_Sahibi, KK_No, KK_SK_Ay, KK_SK_Yil yeterli). Bu standalone "Kart Ekle" UX'ini mümkün kılıyor — kullanıcı checkout'tan ayrı, "Hesabım" sayfasında kartını önceden kaydedebilir.

iyzico ve PayTR'da bu lüks yok (her ikisi de standalone tokenize için ek hack — iyzico CardStorage /cardstorage/card, PayTR 1 TL dummy charge — kullanıyor).

#V4 — KS_Tahsilat charge için CVV (KK_CVC) gerekli

KS_Tahsilat charge sırasında KK_CVC alanı gerekli. Yani saklı karttan ödeme akışında her seferinde kullanıcıdan CVV isteyeceğiz (BDDK ile uyumlu — saklı kart "tek tık" değil, kullanıcı CVV girmeli).

#V5 — `Tutar` format tutarsızlığı (charge vs refund)

Saved-card charge mevcut charge ile aynı format (virgül).

#V6 — IP whitelist `service_ks.asmx` için de gerekli

Mevcut service_turkpos_prod.asmx IP whitelist sorunu (docs/integrations/param.md quirk #3 / project_param_sandbox_blocked.md memory) out.ws/service_ks.asmx için de geçerli — aynı Param WAF VPS IP'mizi blokluyor. Cevap geldiğinde her iki host için de access açılması istenmeli (mail draft'ında belirt).

#V7 — `cache_wsdl` saved-card için de kritik

Mevcut Param charge quirk #6'daki gibi — WSDL_CACHE_BOTH flag'i saved-card metodlarında da gerekli. İki ayrı WSDL var, ikisi de cache'lenmeli.

#V8 — `KS_Tahsilat` 3DS yanıtı `UCD_HTML` veya `UCD_URL` olabilir

Param sandbox bazen 3DS challenge'ı tam HTML form (UCD_HTML) olarak, bazen sadece endpoint URL'i (UCD_URL) olarak döndürüyor — merchant hesap ayarına bağlı, deterministik değil. ParamCardVault her ikisini de handle ediyor: UCD_HTML boşsa UCD_URL'i auto-submit POST form'una sarıyor (wrap_ucd_url_post()). Sonuçta downstream renderer (Iyzico3DSBridge::issue()) tek shape görüyor.

Gurmepos-pro v6'da da aynı pattern (custom-form-data.php view ile UCD_URL'e POST). Spec'te UCD_URL dökümante değil ama gerçek sandbox response'larında karşımıza çıkıyor.

#V9 — `KS_Tahsilat` callback shape'i `TP_WMD_Pay` finalize'siz farklı

Regular TP_WMD_UCD callback'i md/mdStatus/orderId/islemGUID shape'ini gönderir → bizim handler TP_WMD_Pay finalize call'ı yapar. KS_Tahsilat callback'i farklı: bank ACS settlement sonucunu doğrudan TURKPOS_RETVAL_* alanları olarak post eder (TURKPOS_RETVAL_Sonuc=1 → success, TURKPOS_RETVAL_Islem_ID → transaction_id, TURKPOS_RETVAL_Siparis_ID → order_id). Finalize SOAP çağrısı yok.

ParamCallbackController::handle_callback shape'i isset(TURKPOS_RETVAL_Sonuc) ile detect ediyor → varsa handle_saved_card_callback (TP_WMD_Pay'siz), yoksa mevcut validate3DCallback path'i (TP_WMD_Pay'li). Gurmepos-pro v6'da da bu ayrım var (process_callback içinde need_use_saved_card() branch).

#V10 — Save-during-checkout: `TP_WMD_UCD` kullan, `KS_Tahsilat` değil

"Bu kartı kaydet" + fresh PAN senaryosunda KS_Kart_Ekle (silent save, 3DS'siz) → ardından TP_WMD_UCD (regular 3DS charge) tercih ediliyor. KS_Tahsilat'a gerek yok — PAN hâlâ scope'ta, normal charge flow'u zaten 3DS yapıyor, iki ayrı 3DS challenge'a gerek yok.

KS_Tahsilat SADECE saved-card-selector path'inde (PAN scope'ta yok) kullanılır.

Hard abort vs soft fallback kararı: KS_Kart_Ekle fail ederse charge denemiyoruz, checkout fail oluyor. Gurmepos-pro v6 pattern'i — gerekçe: save fail genelde bad card data demek, charge da fail edecekti zaten. Soft fallback ("save'siz devam") kullanıcıya "saklamadık ama ödedin" durumu yaratır, kafa karıştırıcı.

7.7. Sandbox testi açık sorular (IP whitelist sonrası)

KS_Kart_Ekle enabled mi (CLIENT_CODE 42469 ile)? Sonuc=1 dönüyor mu?
KS_Tahsilat 3DS akışı UCD_HTML mü Yonlendirme_URL mü dönüyor (mevcut TP_WMD_UCD farklılığı var)?
KS_GUID rotasyonu — kart vade dolduğunda token nasıl geçersizleşiyor?
KS_Tahsilat taksitli charge destekliyor mu (Taksit > 1)?
KK_SK_Yil 4-haneli mi (2030) yoksa 2-haneli mi (30) bekleniyor?
KS_Kart_Ekle yanıtında masked BIN/last4/brand alanları var mı, yoksa biz tahmin (BIN ilk 6, last4 son 4) ile mi dolduracağız?

7.8. Kaynaklar

Param Dev Portal — Kart Saklama
TurkPos charge WSDL: https://posws.param.com.tr/turkpos.ws/service_turkpos_prod.asmx?wsdl
Saved-card WSDL: https://posws.param.com.tr/out.ws/service_ks.asmx?wsdl (ayrı endpoint)
Sandbox: aynı host'ların testposws.param.com.tr versiyonu

8. Değişiklik geçmişi

param — Param Pos (TurkPos / Doruk Yazılım)