4. Widget Entegrasyonu

4.1 Script Dahil Etme

<script src="https://cdnecozum.com/static/finrota-widget/v1.0.0/index.umd.js"></script>

4.2 Widget Başlatma

FinrotaPay.init({
   token: "WIDGET_TOKEN",
   amount: 6650,
   currency: "TRY",
   mode: "modal",
   containerId: "payment-container",
   environment: "prod",

   onReady() {},
   onSuccess(data) {},
   onFail(error) {},
   onClose() {}
});

4.3 Widget Eventleri

Event	Açıklama
onReady	Checkout hazır
onSuccess	Ödeme başarılı
onFail	Hata oluştu
onClose	Kullanıcı kapattı

5. Widget Ödeme Akışı

Widget entegrasyonunda ödeme süreci frontend (widget) ve backend (merchant server) arasında hibrit olarak yürütülür.

1 – AccessToken Alınır (Backend)

Merchant backend, Finrota API üzerinden AccessToken alır.

POST /auth/api/token/connect

2 – WidgetToken Üretilir (Backend)

AccessToken kullanılarak işlem bazlı WidgetToken oluşturulur.

• GET /b2c/widget/token
• Authorization: Bearer {AccessToken}

Bu token

• Her ödeme için özeldir
• 20 dakika geçerlidir

3 – Widget Frontend’e Aktarılır

Backend tarafından üretilen WidgetToken, frontend’e iletilir.

4 – Widget Başlatılır (Frontend)

FinrotaPay.init({
   token: "WIDGET_TOKEN",
   amount: 2750,
   currency: "TRY",
   mode: "modal",
   containerId: "payment-container",
   environment: "prod"
});

5 – Kullanıcı Kart Bilgilerini Girer (Widget UI)

• Kart numarası
• CVV
• Son kullanma tarihi
• Taksit seçimi (dinamik olarak gelir)

Bu aşamada

• Widget → /paymentOptions endpoint’ini otomatik çağırır
• Uygun POS ve taksit seçeneklerini listeler

6 – Widget PreparePayment Çağrısı (Internal)

Kullanıcı ödeme butonuna bastığında widget

• POST /b2c/widget/preparePayment

çağrısını yapar ve

• Kart bilgileri
• Seçilen taksit (installmentToken)

Finrota’ya iletilir

Bu adım sonucunda
→ prepareToken oluşturulur

7 – onSuccess Event’i Tetiklenir (Frontend)

onSuccess(data) {

  // ödeme hazır

}

Bu event

• Ödemenin tamamlandığı anlamına gelmez
• Sadece ödeme request’inin hazır olduğunu gösterir

8 – Merchant Backend’e İstek Atılır

Frontend, kendi backend’ine aşağıdaki bilgileri gönderir:

Alan	Açıklama
prepareToken	Ödeme için oluşturulan token
amount	İşlem tutarı
diğer metadata	sipariş bilgisi vb.

9 – Payment Endpoint Çağrılır (Backend)

Merchant backend

• POST /b2c/widget/payment
• Authorization: Bearer {AccessToken}

çağrısını yapar

10 – Ödeme Sonucu

3D Secure Senaryosu

Response

{

 "paymentType": "RedirectUrl",

 "redirectTo": "3D\_URL"

}

Akış

1. Frontend → kullanıcıyı redirect eder
2. Banka → OTP doğrulaması
3. Kullanıcı → returnUrl’e döner

3D’siz Senaryo

{

 "paymentType": "DirectSale",

 "success": true

}

→ Ödeme direkt tamamlanır

Kritik Davranışlar

Token Yönetimi

Token	Nerede Kullanılır
AccessToken	Backend
WidgetToken	Frontend (widget init)
PrepareToken	Backend payment çağrısı

Event Yönetimi

Event	Gerçek Anlamı
onReady	UI hazır
onSuccess	ödeme hazırlandı (henüz çekim yok)
onFail	validation / sistem hatası
onClose	kullanıcı çıkış yaptı

En Çok Yapılan Hatalar

• onSuccess → ödeme tamamlandı sanılması
• Backend’e gitmeden işlem bitirilmesi
• AccessToken ile widget init yapılması
• PrepareToken yerine WidgetToken kullanılması

6. Widget Token Üretimi

Endpoint: GET /b2c/widget/token

Header

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

Response

Alan	Tip	Açıklama
token	string	Widget işlemi için kullanılacak token

Özellikler

• Parametre almaz
• 20 dakika geçerlidir