Hızlı Başlangıç

Bu sayfa ilk tahsilatı baştan sona dört adımda gösterir. Örnekler test ortamı içindir ve 150,00 TL’lik bir tahsilatı anlatır.

Başlamadan önce şunlar elinizde olmalı: test API anahtarınız, terminalId (terminal kimliği) değeriniz ve test kartı. Ayrıntı için Hesap Açılışı ve İlk Giriş ve Test Kartı sayfalarına bakın.

Örneklerdeki kimlikler ve tarihler temsilidir. Tutarlar kuruş cinsinden tamsayıdır: 150,00 TL → 15000. Ayrıntı için Tutar ve Para Birimi sayfasına bakın.

1. Taksit ve toplam tutarı sorgulayın

Kart sahibi kartının ilk 8 hanesini girdiğinde sunucunuz POST /v1/installment-options ucunu çağırır. İstekte kartın ilk 8 hanesi (bin), terminal ve anapara bulunur. Anapara baseAmount alanıdır.

curl -X POST https://test-api.lydiagate.com/v1/installment-options \
  -H "Authorization: Bearer ldg_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "bin": "54308115",
    "terminalId": "trm_3Kd9x",
    "baseAmount": 15000
  }'

Yanıt 200 OK:

{
  "cardBrand": "paraf",
  "cardFamily": "credit",
  "cardBank": "Örnek Banka",
  "options": [
    { "installmentCount": 1, "rateBps": 375, "fixedFee": null,
      "baseAmount": 15000, "commissionAmount": 563, "customerShareAmount": 563, "totalAmount": 15563 },
    { "installmentCount": 3, "rateBps": 525, "fixedFee": null,
      "baseAmount": 15000, "commissionAmount": 788, "customerShareAmount": 788, "totalAmount": 15788 }
  ],
  "commissionBasis": "net"
}

Her satır bir taksit seçeneğidir. installmentCount taksit sayısıdır ve tek çekim için 1 döner. totalAmount kart sahibinden çekilecek toplam tutardır. commissionAmount bankaya bildirilecek komisyondur. commissionBasis her zaman net döner. Bu, komisyonun anaparanın üstüne eklendiği anlamına gelir.

Listeyi olduğu gibi kart sahibine gösterin. Listede olmayan bir taksit sayısıyla ödeme oluşturmayın. Ayrıntı: Taksit ve Toplam Tutar Sorgusu.

Not

Terminalinize tanımlı taksit sayıları bu örnekten farklı olabilir. Liste boş dönerse bu kartla bu terminalde ödeme alınamaz. Bu durumda kart sahibinden başka bir kart isteyin.

2. Ödeme oluşturun

Kart sahibi tek çekimi seçsin. amount alanına seçilen satırın totalAmount değerini yazın. installment alanına seçilen taksit sayısını yazın. Bu istekte kart yoktur.

curl -X POST https://test-api.lydiagate.com/v1/payments \
  -H "Authorization: Bearer ldg_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15563,
    "partnerTxCode": "SU-2026-10-000123",
    "terminalId": "trm_3Kd9x",
    "installment": 1,
    "description": "Su faturası Ekim 2026",
    "returnUrl": "https://ebelediye.example/odeme/sonuc"
  }'

Alan	Anlamı
amount	Kart sahibinden çekilecek toplam tutar. Sorgudan gelen totalAmount değeri.
partnerTxCode	Sizin tarafınızda bu tahsilata özgü işlem kodu. Tahakkuk, sicil ya da fatura numaranızı kullanın.
terminalId	LydiaGate’in size ilettiği terminal kimliği.
installment	Seçilen taksit sayısı. Tek çekim için 1.
description	İşlem açıklaması. İsteğe bağlı.
returnUrl	3D Secure sonrası kart sahibinin döneceği adres.

Yanıt 201 Created:

{
  "paymentCode": "pay_7Hq2bL",
  "status": "initiated",
  "paymentRef": "pr_3Kd9xQ1w2E",
  "handoffUrl": "https://pay.lydiagate.example/checkout",
  "idempotentReplay": false
}

paymentCode ödemenin kalıcı kimliğidir. Sorgu ve iade çağrılarında bunu kullanırsınız. paymentRef tek kullanımlık ödeme referansıdır ve yalnız bir sonraki adımda kartla birlikte gönderilir. handoffUrl kart sahibinin tarayıcısını yönlendireceğiniz LydiaGate 3DS Relay adresidir. Bu adresi yanıttan olduğu gibi kullanın.

Not

Yanıtı alamazsanız aynı partnerTxCode ile aynı isteği tekrar gönderin. Yeni bir kod üretmeyin. Ödeme daha önce oluştuysa yanıt 200 OK ve idempotentReplay: true olur ve ikinci bir tahsilat oluşmaz. Ödeme oluşmadıysa istek normal şekilde 201 döner. Ayrıntı: Ödeme Oluştur.

İstek 403 ve payment_acceptance_held alırsa hesabınız henüz ödeme almıyor demektir. Nedeni ödeme kabul durumu ucundan öğrenin.

3. Kart sahibini LydiaGate 3DS Relay’e yönlendirin

Kendi ödeme ekranınızda topladığınız kartı ve paymentRef değerini kart sahibinin tarayıcısından handoffUrl adresine form ile gönderirsiniz. LydiaGate 3DS Relay bankanın 3D Secure adımını kendisi yürütür. Banka formunu siz kurmazsınız.

Web: form gönderimi

Kart sahibinin tarayıcısı, handoffUrl alanındaki yönlendirme adresine bir form ile POST isteği gönderir. Bu örnekte kart maskelidir. Gerçek değer kart sahibinin tarayıcısının belleğinden gelir. Gerçek kart numarasını dokümana ya da loga yazmayın.

<form id="lydiagate-handoff" method="POST" action="https://pay.lydiagate.example/checkout">
  <input type="hidden" name="paymentRef" value="pr_3Kd9xQ1w2E" />
  <input type="hidden" name="pan" value="4242 42** **** 4242" />
  <input type="hidden" name="expireMonth" value="12" />
  <input type="hidden" name="expireYear" value="28" />
  <input type="hidden" name="cv2" value="***" />
</form>
<script>document.getElementById('lydiagate-handoff').submit();</script>

Gönderimden sonra her şey LydiaGate 3DS Relay’de yürür. Relay bankanın 3D Secure adımını başlatır. Kart sahibi 3D Secure doğrulamasını tamamlar. LydiaGate sonucu işler. Sonra kart sahibinin tarayıcısı HTTP 303 yönlendirmesiyle returnUrl adresinize döner. Banka formunu siz kurmazsınız. Otomatik gönderilen formu LydiaGate 3DS Relay üretir.

Mobil: WebView

Mobil uygulamada akış aynıdır. Tek fark, tarayıcı bağlamını bir WebView ile yaratmanızdır.

1. Kartı uygulamanızın kendi ekranında toplayın.
2. Bir WebView açın.
3. Kart ile paymentRef değerini handoffUrl adresine POST isteğiyle gönderin:
   • Android: WebView.postUrl(handoffUrl, body). Gövde, application/x-www-form-urlencoded kodlanmış paymentRef ve kart alanlarıdır.
   • iOS: httpMethod = "POST" ayarlı bir URLRequest ile WebView’i yükleyin.
4. 3D Secure WebView içinde tamamlanır. Sonunda WebView sizin returnUrl adresinize iner.

Not

Navigasyonu kendiniz dinleyin. LydiaGate tarafında mobile özel hiçbir şey yoktur. Standart 303 → returnUrl dönüşü yapılır. Deep-link kullanılmaz. Uygulamanız WebView navigasyonunu dinler ve returnUrl adresine ulaşıldığını kendisi tespit eder. WebView’de JavaScript ve çerez açık olmalıdır. Aksi halde 3D Secure çalışmaz.

3D Secure tamamlanınca 3DS Relay kart sahibini HTTP 303 yönlendirmesiyle sizin returnUrl adresinize gönderir. Kart sahibinin bu adımı tamamlaması için 135 dakika süresi vardır.

Dikkat

returnUrl adresine gelen bilgi kart sahibinin tarayıcısından geçer. Bu bilgiyi kesin sonuç olarak kabul etmeyin. Tahsilatı tamamlanmış saymadan önce sonucu sunucu tarafında doğrulayın. Doğrulama bir sonraki adımdadır.

4. Sonucu doğrulayın

Kesin sonucu iki yoldan öğrenirsiniz. İkisi de aynı sonuca götürür. Webhook anlıktır, sorgu kesindir.

Webhook: Ödeme sonuçlanınca LydiaGate webhook adresinize bir bildirim gönderir. Gövde küçüktür ve yalnız olay tipiyle ödeme kodunu taşır:

{
  "id": "whd_a1b2c3",
  "type": "payment.captured",
  "paymentCode": "pay_7Hq2bL",
  "occurredAt": "2026-10-23T09:05:11Z"
}

Webhook’u tetikleyici olarak kullanın. Kararınızı sorgunun sonucuna göre verin. İmza doğrulama ve yeniden deneme kuralları: Webhooks.

Sorgu: Webhook geldiğinde ya da kart sahibi dönüş adresine düştüğünde ödemeyi sorgulayın:

curl https://test-api.lydiagate.com/v1/payments/pay_7Hq2bL \
  -H "Authorization: Bearer ldg_test_…"

Yanıt 200 OK:

{
  "paymentCode": "pay_7Hq2bL",
  "partnerTxCode": "SU-2026-10-000123",
  "status": "captured",
  "amount": 15563,
  "currency": "try",
  "installmentCount": 1,
  "maskedPan": "543081******9115",
  "cardFamily": "credit",
  "cardBank": "Örnek Banka",
  "appliedRateBps": 375,
  "appliedFixedFee": null,
  "commissionAmount": 563,
  "netToPartner": 15000,
  "expectedValueDate": "2026-10-24",
  "refunds": [],
  "createdAt": "2026-10-23T09:00:00Z",
  "updatedAt": "2026-10-23T09:05:11Z"
}

Alan	Anlamı
status	Ödemenin kesin durumu. captured tahsilatın onaylandığı anlamına gelir.
amount	Kart sahibinden çekilen toplam tutar.
commissionAmount	Bankaya bildirilen komisyon.
netToPartner	Kurumunuzun hesabına geçecek anapara.
expectedValueDate	Paranın hesabınıza geçmesi beklenen tarih.
maskedPan	Maskeli kart numarası. Tam kart numarası hiçbir zaman dönmez.

Kart handoff’u yapılmadan önce karta bağlı alanlar null döner. Kart LydiaGate 3DS Relay’e ulaşınca bu alanlar dolar ve ödeme yine initiated kalabilir. Durumların tamamı: Ödeme Durumları. Alanların tamamı: Ödeme Sorgula.

Aynı ödemeyi kendi işlem kodunuzla da sorgulayabilirsiniz: GET /v1/payments?partnerTxCode=SU-2026-10-000123.

Sonraki adımlar

• Ödeme Akışı: akışın bütünü ve bir ödemenin tek kart denemesi olması.
• Ödeme Oluştur: tüm istek ve yanıt alanları, hız limitleri, hatalar.
• Kart Handoff: web ve mobil yönlendirme ayrıntıları.
• İade ve İptal: tahsilatı geri alma.