Sigorta Şirketleri – TCKN ile Ödeme

Genel Bakış #

Bu entegrasyon sigorta şirketlerine özel bir ödeme akışıdır. Standart sanal POS ödemesinden farkı, kart sahibinin TC Kimlik Numarası (TCKN), kartın BIN numarası ve kartın son dört hanesi gibi ek kimlik bilgilerinin de işleme dahil edilmesidir. Bu sayede sigortalıya ait poliçe ödemeleri güvenli şekilde eşleştirilebilir.

Gereksinimler #

Aşağıdaki koşulların sağlanmış olması gerekmektedir. Eksik bir koşul, ödeme işleminin reddedilmesine yol açar.

MCC 6300 — Üye işyerinde Sigortaya ait MCC (Merchant Category Code) 6300 tanımlı olmalıdır. Bu kod; sağlık, hayat ve genel sigorta şirketlerine ait ödemeleri belirtir. Tanımlanmamış ise paynkolay destek ekibiyle iletişime geçin.
Non Secure (NonSecure) İşlem Yetkisi — Kartın 3D Secure doğrulamasından geçirilmediği Non Secure akış için üye işyerinin bu yetkiye sahip olması gerekmektedir. Yetkinin açık olup olmadığını panelinizden ya da destek ekibimizden öğrenebilirsiniz.

Sigorta ödeme servisi, sigorta şirketlerine özel bir API endpointi kullanır: POST /Vpos/v1/InsurancePayment. Standart ödeme endpointinden (/Vpos/v1/Payment) farklıdır.

Hash Hesaplama #

Sigorta ödemelerinde kullanılan hashDataV2 değeri, standart ödemelerden farklı parametreler içerir; kart BIN numarası, kartın son dört hanesi ve kart sahibinin TC Kimlik Numarası da hash hesaplamasına dahil edilir. Hash hesaplama yöntemi hakkında genel bilgi için Hash İsteği sayfasına bakın.

Hash string'i aşağıdaki sırayla birleştirilmelidir (değerler arasında | karakteri kullanılır):

sx | clientRefCode | amount | successUrl | failUrl | rnd | CardBinNumber | CardLastFour | CardHolderIdentity | MerchantSecretKey

Oluşturulan hash string'i SHA-512 algoritması ile hashlenir ve sonuç Base64 olarak encode edilerek hashDataV2 parametresi olarak gönderilir:

$hashstr = $sx . '|' . $clientRefCode . '|' . $amount . '|' . $successUrl . '|' . $failUrl . '|' . $rnd . '|' . $CardBinNumber . '|' . $CardLastFour . '|' . $CardHolderIdentity . '|' . $merchantSecretKey;
$hashDataV2 = base64_encode(hash('sha512', $hashstr, true));

Parametre	Açıklama
`sx`	Size verilen SX değeri (panelden alınır)
`clientRefCode`	Kendi referans numaranız
`amount`	Ödeme tutarı (ondalık ayraç olarak nokta kullanılır, örn: `30.00`)
`successUrl`	Başarılı işlem sonrası yönlendirme URL'i
`failUrl`	Başarısız işlem sonrası yönlendirme URL'i
`rnd`	Rastgele / zaman damgası değeri (örn: `2025-03-05T15:27:05.597196`)
`CardBinNumber`	Kartın BIN numarası (ilk 8 hane)
`CardLastFour`	Kartın son dört hanesi
`CardHolderIdentity`	Kart sahibinin TC Kimlik Numarası (TCKN)
`MerchantSecretKey`	Size verilen gizli anahtar (panelden alınır)

Sigorta Ödeme Parametreleri #

Aşağıdaki tablo POST /Vpos/v1/InsurancePayment endpointine gönderilmesi gereken tüm parametreleri açıklamaktadır. Sigorta ödeme endpointi standart ödeme parametrelerine ek olarak CardBinNumber, CardLastFour ve CardHolderIdentity alanlarını zorunlu kılar.

Parametre	Zorunlu	Örnek Değer	Açıklama
`sx`	Evet	163164707\|G2l+Lv3m...	SX değeriniz
`clientRefCode`	Evet	REF-12345	İşleme ait referans numarası
`successUrl`	Evet	https://...	Başarılı ödeme sonrası yönlendirme adresi
`failUrl`	Evet	https://...	Başarısız ödeme sonrası yönlendirme adresi
`amount`	Evet	30.00	Ödeme tutarı (nokta ile ayrılmış ondalık)
`installmentNo`	Evet	1	Taksit sayısı; tek çekim için `1`
`cardHolderName`	Evet	Ad Soyad	Kart üzerindeki isim
`encodedValue`	Evet	eHlTOW...	Şifrelenmiş kart bilgisi (Non Secure işlemlerde kullanılır)
`use3D`	Evet	false	Sigorta ödemeleri Non Secure olduğundan `false` gönderilmelidir
`transactionType`	Evet	SALES	İşlem tipi; her zaman `SALES`
`rnd`	Evet	2025-03-05T15:27:05.597196	Zaman damgası / rastgele değer
`hashDataV2`	Evet	HotxQ38B...	Hash değeri (yukarıdaki formüle göre hesaplanır)
`currencyNumber`	Evet	949	Para birimi kodu; TL için `949`
`merchantCustomerNo`	Hayır	N123546	Üye işyerine ait müşteri numarası
`CardBinNumber`	Evet	49384101	Kartın ilk 8 hanesi (BIN)
`CardLastFour`	Evet	5591	Kartın son 4 hanesi
`CardHolderIdentity`	Evet	74924239426	Kart sahibinin TC Kimlik Numarası
`cardHolderIP`	Hayır	172.16.121.57	Müşterinin IP adresi

Postman Koleksiyonu #

Aşağıdaki Postman koleksiyonunu indirerek sigorta ödeme entegrasyonunu hızlıca test edebilirsiniz. Koleksiyondaki Sigorta Şirketleri TC ile Ödeme Alma klasörü; hash'i otomatik hesaplayan bir ön-istek (pre-request) scripti içerir — sx, clientRefCode, amount gibi form alanlarını doldurmak yeterlidir, hashDataV2 değeri otomatik üretilir.

Postman Koleksiyonunu İndir

Koleksiyonu Postman'e aktardıktan sonra Collection Variables kısmından sx ve merchantSecretKey değerlerinizi kendi test değerlerinizle güncelleyin.