Alışveriş Kredisi Başvuru Yönetimi

Kredi Başvurusu

Müşteri adına kredi başvurusu oluşturur. Bu servisi çağırmadan önce Ön Kredi Değerlendirmesi servisinin çağrılması zorunludur.

Endpoint: /loans/v1/facilitate/application/{preApprovedReferenceId} Method: POST Content-Type: application/json

Parametreler

Parametre	Tip	Açıklama
preApprovedReferenceId	string (path)	Ön Kredi Değerlendirmesi servisinden dönen `referenceId` değeri

İstek Parametreleri

{
  "nationalIdentityNumber": "12345678901",
  "gsmNumber": "5551234567",
  "orderId": "ORDER-12345",
  "orderDate": "2025-12-24T10:30:00",
  "totalTerm": 6,
  "timeToLive": 1735041000,
  "callbackUrl": "https://yourdomain.com/callback",
  "cart": {
    "price": {
      "itemsPrice": 20000.00,
      "shippingPrice": 100.00,
      "totalPrice": 20100.00
    },
    "items": [
      {
        "productName": "Ürün Adı",
        "categoryCode": "Kategori Kodu",
        "quantity": 1,
        "price": 20000.00,
        "totalPriceWithoutDiscounts": 20000.00,
        "totalPrice": 20000.00,
        "sellerExternalId": "SELLER-001",
        "commissionRate": 1.00,
        "withholdingTax": 0.10,
        "marketplaceCost": 2.00
      }
    ]
  }
}

Parametre	Tip	Açıklama	Zorunlu
nationalIdentityNumber	string	Müşterinin T.C. Kimlik Numarası	Zorunlu
gsmNumber	string	Müşterinin telefon numarası (5XXXXXXXXX formatında)	Zorunlu
orderId	string	Sipariş numarası (benzersiz olmalı)	Zorunlu
orderDate	string	Sipariş tarihi (ISO 8601: YYYY-MM-DDTHH:mm:ss)	Zorunlu
totalTerm	integer	Seçilen vade sayısı	Zorunlu
timeToLive	integer	Başvurunun geçerlilik süresi (Unix timestamp)	Zorunlu
callbackUrl	string	Başvuru sonucu için PaynKolay’ın geri dönüş yapacağı URL	Zorunlu
cart	object	Sepet bilgileri (Ön Onay Sorgulama ile aynı formatta)	Zorunlu
cart.items[].sellerExternalId	string	Satıcı ID	İsteğe Bağlı
cart.items[].commissionRate	number	Komisyon oranı (%)	İsteğe Bağlı*
cart.items[].commissionAmount	number	Komisyon tutarı (TL)	İsteğe Bağlı*
cart.items[].withholdingTax	number	Stopaj vergisi	İsteğe Bağlı
cart.items[].marketplaceCost	number	Pazaryeri maliyeti	İsteğe Bağlı

Not: commissionRate ve commissionAmount alanlarından yalnızca bir tanesi dolu gönderilmelidir.

Yanıt Örneği

{
  "success": true,
  "referenceId": "81acf2ef-448c-43f3-978e-52757b4c621b",
  "referenceCode": "REF123456",
  "bankApproved": true,
  "bankResponseCode": "0",
  "bankResponseMessage": "İşlem Başarılı",
  "bankRedirectionUrl": "https://dpuat.aktifbank.com.tr/WebCreditApi/WebCredit?ecommerceref=3bb0f009-d15c-4eee-b2a1-cbc3cd959381",
  "paymentPlan": {
    "lendingAmount": 20100,
    "interestRate": 4.19,
    "term": 6,
    "totalPaymentAmount": 24101.05,
    "annualEffectiveInterestRate": 88.9781,
    "monthlyPayments": [
      {
        "term": 1,
        "amount": 4016.84,
        "dueDate": "2026-01-24T10:30:00"
      },
      {
        "term": 2,
        "amount": 4016.84,
        "dueDate": "2026-02-24T10:30:00"
      }
    ]
  }
}

Yanıt Parametreleri

Parametre	Tip	Açıklama
success	boolean	İşlemin başarılı olup olmadığını belirtir
referenceId	string	PaynKolay referans ID’si (başvuru sorgulamada kullanılır)
referenceCode	string	PaynKolay referans kodu
bankApproved	boolean	Banka tarafından onaylanıp onaylanmadığını belirtir
bankResponseCode	string	Banka cevap kodu
bankResponseMessage	string	Banka cevap mesajı
bankRedirectionUrl	string	Bankanın yönlendirme URL’si. Müşteri bu URL’ye yönlendirilmelidir.
paymentPlan	object	Ödeme planı bilgileri
paymentPlan.lendingAmount	number	Kredi tutarı (TL)
paymentPlan.interestRate	number	Faiz oranı (%)
paymentPlan.term	integer	Vade sayısı (ay)
paymentPlan.totalPaymentAmount	number	Toplam ödeme miktarı (TL)
paymentPlan.annualEffectiveInterestRate	number	Yıllık efektif faiz oranı (%)
paymentPlan.monthlyPayments	array[object]	Aylık ödeme detayları
paymentPlan.monthlyPayments[].term	integer	Taksit numarası
paymentPlan.monthlyPayments[].amount	number	Aylık ödeme miktarı (TL)
paymentPlan.monthlyPayments[].dueDate	string	Ödeme tarihi (ISO 8601)

Önemli Notlar

Yönlendirme: Başvuru başarılı olduğunda, bankRedirectionUrl değerini kullanarak müşteriyi bankanın sayfasına yönlendirmelisiniz.
Callback: Banka işlemi tamamlandıktan sonra, PaynKolay callbackUrl adresinize POST isteği gönderecektir.
referenceId: Bu değeri saklayın - başvuru durumunu sorgulamak için kullanılacaktır.

Başvuru Sorgulama

Belirli bir kredi başvurusunun durumunu sorgular.

Endpoint: /loans/v1/facilitate/query/loan/{loanApplicationReferenceId} Method: GET

Parametreler

Parametre	Tip	Açıklama
loanApplicationReferenceId	string (path)	Kredi Başvurusu işleminden dönen `referenceId` değeri

Yanıt Örneği

{
  "loanApplication": {
    "bankType": "AKTIFBANK",
    "bankApplicationId": "BANK-APP-12345",
    "referenceId": "81acf2ef-448c-43f3-978e-52757b4c621b",
    "referenceCode": "REF123456",
    "merchantNo": 4003,
    "orderId": "ORDER-12345",
    "nationalIdentityNumber": "12345678901",
    "gsm": "5551234567",
    "totalTerm": 6,
    "type": "SHOPPING_LOAN",
    "isApproved": true,
    "timeToLive": 1735041000,
    "bankRedirectionUrl": "https://...",
    "applicationDate": "2025-12-24T10:30:00Z",
    "orderDate": "2025-12-24T10:30:00Z",
    "status": "APPROVED",
    "merchantCallbackUrl": "https://yourdomain.com/callback",
    "cart": {
      "totalPrice": 20100,
      "shippingPrice": 100,
      "items": [
        {
          "categoryCode": "ELECTRONICS",
          "name": "Ürün Adı",
          "quantity": 1,
          "price": 20000,
          "priceWithoutDiscounts": 20000
        }
      ]
    },
    "paymentPlan": {
      "lendingAmount": 20100,
      "interestRate": 4.19,
      "term": 6,
      "totalPaymentAmount": 24101.05,
      "totalRefundAmount": 0,
      "annualEffectiveInterestRate": 88.9781,
      "monthlyEffectiveInterestRate": 7.4148,
      "monthlyPayments": [
        {
          "term": 1,
          "amount": 4016.84,
          "dueDate": "2026-01-24T10:30:00Z",
          "details": "1. Taksit"
        }
      ]
    }
  }
}

Başvuru Durumları (Status)

Durum	Açıklama
NEW	Yeni başvuru oluşturuldu
STARTED	Başvuru işleme alındı
FAILED	Başvuru başarısız oldu
APPROVED	Başvuru onaylandı
REJECTED	Başvuru reddedildi
CANCELLED	Başvuru iptal edildi
REFUNDED	Tam iade yapıldı
REFUNDED_PARTIAL	Kısmi iade yapıldı
REFUNDED_ANOMALY	İade anomalisi
TIMEOUT	Başvuru zaman aşımına uğradı

Kredi İade İşlemleri

Onaylanan ve kullanılan kredinin iadesini sağlar.

Endpoint: /loans/v1/facilitate/refund/{loanApplicationReferenceId} Method: POST Content-Type: application/json

Parametreler

Parametre	Tip	Açıklama
loanApplicationReferenceId	string (path)	Kredi Başvurusu işleminden dönen `referenceId` değeri

İstek Parametreleri

{
  "refundAmount": 1000.00,
  "sellerList": [
    {
      "trxAmount": 1000.00,
      "refundedCommissionAmount": 10.00,
      "sellerExternalId": "SELLER-001",
      "withholdingTax": 2.00
    }
  ]
}

Parametre	Tip	Açıklama	Zorunlu
refundAmount	number	İade edilecek tutar (minimum 0.01 TL)	Zorunlu
sellerList	array[object]	Satıcı bazlı iade bilgileri (pazaryeri için)	İsteğe Bağlı
sellerList[].trxAmount	number	İşlem tutarı	İsteğe Bağlı
sellerList[].refundedCommissionAmount	number	İade edilen komisyon tutarı	İsteğe Bağlı
sellerList[].sellerExternalId	string	Satıcı ID	İsteğe Bağlı
sellerList[].withholdingTax	number	Stopaj vergisi	İsteğe Bağlı

Yanıt Örneği

{
  "bankResponseCode": "0",
  "bankResponseMessage": "İşlem Başarılı",
  "bankReferenceId": "BANK-REF-789",
  "referenceId": "REFUND-REF-456",
  "success": true
}

Yanıt Parametreleri

Parametre	Tip	Açıklama
bankResponseCode	string	Banka cevap kodu (“0” = başarılı)
bankResponseMessage	string	Banka cevap mesajı
bankReferenceId	string	Banka referans numarası
referenceId	string	PaynKolay referans numarası
success	boolean	İşlemin başarılı olup olmadığını belirtir

İade Notları

Tam iade veya kısmi iade yapılabilir
İade tutarı, kredi tutarını aşamaz
İade işlemi sonrası başvuru durumu REFUNDED veya REFUNDED_PARTIAL olarak güncellenir

Kredi Raporlama

Kredilerin raporlanmasını ve listelenmesini sağlar.

Endpoint: /loans/v1/facilitate/reporting Method: GET

Query Parametreleri

Parametre	Tip	Açıklama	Zorunlu
startDate	string	Başlangıç tarihi (ISO 8601)	Zorunlu
endDate	string	Bitiş tarihi (ISO 8601)	Zorunlu
referenceId	string	Belirli bir başvuruyu filtrelemek için	İsteğe Bağlı
statuses	array[string]	Durum filtresi (NEW, APPROVED, vb.)	İsteğe Bağlı
pageNumber	integer	Sayfa numarası	Zorunlu
pageSize	integer	Sayfa başına kayıt sayısı	Zorunlu

Örnek İstek

GET /loans/v1/facilitate/reporting?startDate=2025-12-01T00:00:00Z&endDate=2025-12-31T23:59:59Z&pageNumber=0&pageSize=20&statuses=APPROVED,REJECTED

Yanıt Parametreleri

Sayfalanmış kredi başvuruları listesini döndürür. Her başvuru, Başvuru Sorgulama ile aynı formattadır.

Hata Yönetimi

API, hatalı istekler için uygun HTTP durum kodları ve hata mesajları döndürür.

HTTP Durum Kodları

Kod	Açıklama
200 OK	İşlem başarılı
201 Created	Yeni bir kaynak oluşturuldu
400 Bad Request	Hatalı istek (geçersiz parametreler)
401 Unauthorized	Yetkilendirme hatası (geçersiz token)
403 Forbidden	Erişim izni yok
404 Not Found	Kaynak bulunamadı
500 Internal Server Error	Sunucu hatası

Hata Yanıt Formatı

Hata mesajları genellikle JSON formatında döndürülür:

{
  "success": false,
  "bankResponseCode": "99",
  "bankResponseMessage": "Hata mesajı açıklaması",
  "errorCode": "VALIDATION_ERROR",
  "errorMessage": "Detaylı hata açıklaması"
}

Yaygın Hatalar ve Çözümleri

Hata	Neden	Çözüm
401 Unauthorized	Token geçersiz veya süresi dolmuş	Yeni token alın
400 Bad Request	Eksik veya hatalı parametre	İstek parametrelerini kontrol edin
bankResponseCode != “0”	Banka işlemi başarısız	Banka hata mesajını kontrol edin
TIMEOUT	İşlem zaman aşımına uğradı	Başvuruyu yeniden deneyin

Tam Entegrasyon Akışı

Alışveriş kredisi entegrasyonunun tüm adımlarını sırasıyla takip edin:

1. Kimlik Doğrulama

POST /loans/authenticate
→ Token alın

2. Banka Listesi

POST /loans/v1/facilitate/query/banks
→ Banka listesini alın ve müşteriye gösterin

3. Banka Seçimi ve Oturum

Müşteri banka seçer
POST /loans/v1/facilitate/sessions/{bankCode}
→ referenceId alın (bankSessionReferenceId)

4. Ödeme Simülasyonu (Opsiyonel)

POST /loans/v1/facilitate/simulation/{bankSessionReferenceId}
→ Taksit seçeneklerini müşteriye gösterin

5. Müşteri Bilgileri ve Ön Onay

Müşteriden TC ve GSM bilgisi alın
POST /loans/v1/facilitate/pre-approved/{bankSessionReferenceId}
→ referenceId alın (preApprovedReferenceId)
→ Ön onay durumunu kontrol edin

6. Kredi Başvurusu

POST /loans/v1/facilitate/application/{preApprovedReferenceId}
→ referenceId alın (loanApplicationReferenceId)
→ Müşteriyi bankRedirectionUrl'e yönlendirin

7. Banka İşlemi

Müşteri banka sayfasında işlemi tamamlar
→ PaynKolay callbackUrl'e sonucu gönderir

8. Başvuru Takibi

GET /loans/v1/facilitate/query/loan/{loanApplicationReferenceId}
→ Başvuru durumunu kontrol edin

9. İade (Gerekirse)

POST /loans/v1/facilitate/refund/{loanApplicationReferenceId}
→ İade işlemini gerçekleştirin

En İyi Uygulamalar

Güvenlik

Token’ları güvenli bir şekilde saklayın
HTTPS kullanın (zorunlu)
Müşteri bilgilerini şifreleyin
API anahtarlarını kaynak koduna yazmayın

Performans

Token’ları önbellekleyin (süresi dolana kadar)
Timeout değerlerini uygun ayarlayın
Hata durumlarında retry mekanizması kullanın

Kullanıcı Deneyimi

Açık hata mesajları gösterin
İşlem durumu hakkında bilgilendirin
Yükleme göstergeleri kullanın
Mobil uyumlu tasarım yapın

Veri Yönetimi

referenceId değerlerini saklayın
Başvuru durumlarını düzenli kontrol edin
Log kayıtları tutun
Callback URL’i düzgün yapılandırın

Önceki Adımlar

Alışveriş Kredisi Genel Bakış → - Temel kavramlar ve giriş
API Entegrasyonu → - Kimlik doğrulama ve hazırlık adımları