10. API Entegrasyonu (Detaylı)

Widget kullanılmadan, tüm ödeme süreci merchant backend tarafından yönetilir. Bu yöntem, tam kontrol ve özelleştirme gerektiren entegrasyonlar için önerilir.

10.1 API Ödeme Akışı (Step-by-Step)

1 – AccessToken Alınır

→ /auth/api/token/connect

2 – Taksit ve POS Bilgileri Getirilir

→ /b2c/paymentOptions

3 – Ödeme Başlatılır

→ /b2c/payment

4 – (Opsiyonel) 3D Süreci

• Eğer use3D = true ise
  • redirectTo URL’e yönlendirme yapılır
  • Banka doğrulaması tamamlanır
  • Kullanıcı returnUrl adresine döner

10.2 PaymentOptions

Endpoint: GET /b2c/paymentOptions

Header

Alan	Tip	Zorunlu	Açıklama
Proxy-Authorization	string	✔	Bearer {AccessToken}

Not: API flow’da bazı implementasyonlarda AccessToken kullanılır (widget’tan farkı)

Query Parametreleri

Alan	Tip	Zorunlu	Açıklama
binNumber	string	✔	Kartın ilk 6-8 hanesi
amount	decimal	✔	İşlem tutarı
currency	string	✔	Para birimi

Response Model

Root Object

Alan	Tip	Açıklama
id	int	Kart program ID
name	string	Kart program adı
posTitle	string	POS açıklaması
isDefaultPos	boolean	Varsayılan POS bilgisi
installments	array	Taksit seçenekleri

installments Object

Alan	Tip	Açıklama
currencyId	string	Para birimi
amount	decimal	Toplam işlem tutarı
installment	int	Taksit sayısı
installmentAmount	decimal	Taksit başına düşen tutar
token	string	InstallmentToken (kritik)
processAmount	decimal	İşleme giren tutar
commRate	decimal	Komisyon oranı
posId	int	POS ID
commApplyTypeId	int	Komisyon tipi

Kritik Not

• token alanı (InstallmentToken), ödeme sırasında zorunludur
• Bu token olmadan /payment çağrısı başarısız olur

10.3 Payment

Endpoint: POST /b2c/payment

Header

Alan	Tip	Zorunlu	Açıklama
Authorization	string	✔	Bearer {AccessToken}

Request Body

card Object

Alan	Tip	Zorunlu	Açıklama
cardNumber	string	✔	Kart numarası
cardHolderName	string	✔	Kart üzerindeki isim
cvv	string	✔	CVV
expMonth	int	✔	Son kullanma ay
expYear	int	✔	Son kullanma yıl

Root Alanlar

Alan	Tip	Zorunlu	Açıklama
card	object	✔	Kart bilgileri
returnUrl	string	✔	3D sonrası yönlendirme URL
clientReferenceCode	string	✔	Merchant sipariş referansı
use3D	boolean	✔	3D Secure kullanımı
installmentToken	string	✔	PaymentOptions’tan gelen token
customerIpAddress	string	✔	Kullanıcı IP adresi

Request Örneği

{
 "card": {
   "cardNumber": "4155650100416111",
   "cardHolderName": "Test Test",
   "cvv": "000",
   "expMonth": 12,
   "expYear": 2026
 },
 "returnUrl": "https://merchant.com",
 "clientReferenceCode": "ORDER123",
 "use3D": true,
 "installmentToken": "INSTALLMENT_TOKEN",
 "customerIpAddress": "78.190.57.187"
}

Response Model

Alan	Tip	Açıklama
paymentType	string	RedirectUrl / DirectSale
redirectTo	string	3D yönlendirme URL
orderId	string	Finrota işlem ID
clientReferenceCode	string	Merchant referansı
success	boolean	İşlem sonucu
error	string	Hata mesajı

10.4 3D Secure Akışı

Senaryo

use3D = true gönderildiğinde:

Response

{
 "paymentType": "RedirectUrl",
 "redirectTo": "https://bank-3d-url",
 "success": false
}

Akış

1. Merchant backend → response alır
2. Frontend → kullanıcıyı redirectTo adresine yönlendirir
3. Kullanıcı → bankada OTP doğrular
4. Banka → kullanıcıyı returnUrl adresine yönlendirir
5. Merchant → sonucu işler (başarılı / başarısız)

Kritik Noktalar

• redirectTo mutlaka frontend’de açılmalıdır
• returnUrl endpoint’i idempotent olmalıdır
• Aynı işlem için duplicate kontrol yapılmalıdır

10.5 3D’siz (Direct Sale) Akış

Response

{
 "paymentType": "DirectSale",
 "success": true
}

Akış

• Ödeme anında tamamlanır
• Ek redirect yoktur
• Sonuç response üzerinden alınır

10.6 Hata Senaryoları

Durum	Açıklama
401	Token geçersiz
400	Eksik / hatalı parametre
500	Sistem hatası
success=false	Banka veya ödeme hatası

10.7 API vs Widget Farkı

Konu	API	Widget
Kart verisi	Backend	Frontend
PCI yükü	Merchant	Finrota
UX	Merchant yönetir	Hazır
Token	AccessToken	WidgetToken + AccessToken

14. API Ödeme Akışı (Step-by-Step)

1 – AccessToken Alınır

2 – Taksit ve POS Bilgileri Getirilir

3 – Ödeme Başlatılır

4 – (Opsiyonel) 3D Süreci

Ödeme İptal

Ödeme İade