Genel Bakış

Bu sayfa belediye tahsilat modelini bir bütün olarak anlatır. Para akışını, komisyon hesabını ve entegrasyonun adımlarını burada görürsünüz.

LydiaGate nedir

LydiaGate, kart ödemelerini banka sanal POS’u üzerinden yürüten bir ödeme altyapısıdır. Kurumunuz kendi web sitesinden ya da mobil uygulamasından kart sahibine kartla ödeme yaptırır. LydiaGate bankayla konuşur, 3D Secure doğrulamasını yürütür ve sonucu size bildirir.

LydiaGate kartı sizin yerinize toplamaz. Kartı kendi ödeme ekranınızda toplarsınız. Sonra kart sahibinin tarayıcısını LydiaGate 3DS Relay adresine yönlendirirsiniz. 3DS Relay, kartı ve tek kullanımlık ödeme referansını alan ve bankanın 3D Secure adımını başlatan LydiaGate yüzeyidir.

Para nasıl akar

Tahsilat Halkbank sanal POS’u üzerinden yapılır. Para kart sahibinin bankasından doğrudan kurumunuzun Halkbank hesabına geçer. LydiaGate para akışına girmez. Paranın hesabınıza geçeceği tarihi banka belirler.

Komisyon nasıl eklenir

Belediye modelinde komisyonu kart sahibi öder. Komisyon anaparanın üstüne eklenir ve kart sahibinden toplam tutar çekilir. LydiaGate her ödemede komisyon tutarını bankaya ayrıca bildirir. Banka komisyonu toplam tutardan ayırır. Kurumunuzun hesabına anapara geçer.

Komisyon oranı kartın tipine ve taksit sayısına göre değişir. Bu yüzden toplam tutar ödeme öncesinde her kart için ayrıca sorgulanır. Sorguyu POST /v1/installment-options ucu yapar. Bu uç, taksit ve toplam tutar sorgusudur. Kart girilmeden önce bütün kart tipleri için taksit ve komisyon tablosunu POST /v1/installment-options/overview ucu verir. Bu uç, kartsız taksit görünümüdür.

150 TL örneği

Anapara 150,00 TL ve komisyon oranı %3,75 olsun. API tüm tutarları kuruş cinsinden tamsayı olarak taşır.

Kalem	Tutar	API değeri
Anapara	150,00 TL	15000
Komisyon oranı	%3,75	375
Komisyon	5,63 TL	563
Kart sahibinden çekilen toplam	155,63 TL	15563
Bankaya bildirilen komisyon	5,63 TL	563
Kurumunuzun hesabına geçen	150,00 TL	15000

Komisyon anapara üzerinden hesaplanır: 15000 × 375 / 10000 = 562,5 kuruş. Sonuç en yakın kuruşa yuvarlanır. Tam yarım kuruş yukarı yuvarlanır. Komisyon 563 kuruş olur. Oran baz puan olarak yazılır. Baz puan, yüzdenin yüzde biridir: %3,75 = 375.

Bu hesabı kendiniz yapmazsınız. Sorgu ucu her seçenek için toplam tutarı totalAmount (toplam tutar) alanında hazır döner. Bu değeri olduğu gibi ödeme isteğine yazarsınız.

Hangi işlemler var

• Tahsilat: kart sahibi tek çekim ya da taksitle öder. Taksit seçenekleri ve komisyon tutarları kart girilmeden önce kart tipine göre, kart girilince karta göre sorgulanır.
• İade ve iptal: aynı işlem günü içinde iptal, sonraki işlem günlerinde tam ya da kısmi iade yapılır. İşlem günü bankanın gün sonu kesimine göre belirlenir. İade edilen tutarın komisyon payı da bankaya bildirilir.
• Sorgu: her ödemenin kesin durumunu ve tutar dökümünü API’den çekersiniz.
• Webhook: ödeme ve iade sonuçları sunucunuza anında bildirilir.
• Panel: personeliniz İş Ortağı Paneli’nden işlemleri izler, iade yapar, API anahtarı ve webhook ayarlarını yönetir.

Uçtan uca akış

Düz oklar istektir. Kesikli oklar yanıttır. Numaralar alttaki listeyle aynıdır.

1. Sunucunuz kart girilmeden önce terminalinizdeki bütün taksit seçeneklerini ve her kart tipi için komisyon tutarını POST /v1/installment-options/overview ile çeker. Ödeme ekranınız bu tabloyu kart sahibine gösterir.
2. Kart sahibi ödeme ekranınızda kartını girer.
3. Sunucunuz kartın ilk 8 hanesiyle kesin taksit seçeneklerini ve toplam tutarı sorgular.
4. Kart sahibi taksit seçeneğini seçer.
5. Sunucunuz seçilen toplam tutarla ödeme oluşturur. Bu istekte kart yoktur.
6. Kart sahibinin tarayıcısı kart ve ödeme referansıyla LydiaGate 3DS Relay’e gider.
7. Kart sahibi 3D Secure doğrulamasını tamamlar.
8. Kart sahibi sizin dönüş adresinize geri döner.
9. Sunucunuz kesin sonucu webhook ile öğrenir.
10. Sunucunuz sonucu GET /v1/payments/{paymentCode} ile doğrular.

Web ve mobil arasında fark yoktur. Mobilde tarayıcı yerine WebView kullanılır.

Bu dokümanda ne var

• Başlangıç: hesabınızı kullanıma hazır hale getirme, API anahtarı, ortam adresleri, test kartı ve ilk tahsilat.
• Tahsilat: ödeme akışı, kartsız taksit görünümü, taksit ve toplam tutar sorgusu, ödeme oluşturma, kart handoff, sorgulama, iade ve iptal.
• Webhooks: tahsilat ve iade sonuçlarının sunucunuza bildirilmesi.
• Hata kodları: API’nin döndürdüğü hata kodları ve anlamları.
• Panel kılavuzu: İş Ortağı Paneli’ndeki ekranlar ve yetkiler.
• API referansı: API uçlarının alan alan tanımı.

Sonraki adımlar

• Hesap Açılışı ve İlk Giriş: hesabınızı kullanıma hazır hale getirin.
• API Anahtarı ile Erişim: isteklerinizi yetkilendirin.
• Hızlı Başlangıç: ilk tahsilatı dört adımda yapın.