Deposit Payment Page

depositUrl ile kullanıcıyı Pientegra hosted deposit page'e yönlendirme modeli.

Deposit flow'da Pientegra External API doğrudan kullanıcı ekranı render etmez. Partner backend önce POST /external/deposits çağırır, Pientegra response içinde signed depositUrl döner. Kullanıcı bu URL'e yönlendirilir.

Bu sayfa, depositUrl'in frontend tarafında nasıl kullanılacağını ve integration ekibinin hangi sorumlulukları üstleneceğini anlatır.

Flow

1. Kullanıcı partner sitede deposit amount seçer.
2. Partner frontend kendi backend'ine request atar.
3. Partner backend Pientegra'ya POST /external/deposits gönderir.
4. Pientegra intent oluşturur ve depositUrl döner.
5. Partner frontend kullanıcıyı depositUrl'e yönlendirir.
6. Kullanıcı hosted page'de banka bilgilerini görür ve transfer yaptığını işaretler.
7. Pientegra deposit'i inceledikten sonra intent.approved veya intent.rejected webhook'u gönderir.

Page content

Hosted deposit page tenant branding ve published page settings'e göre render edilir. Kullanıcının gördüğü temel bilgiler:

Alan	Açıklama
Amount	Kullanıcının yatırması gereken exact amount.
Account holder	Transfer yapılacak hesabın sahibi.
IBAN	Transfer yapılacak account IBAN'ı.
Reference	Support ve reconciliation için reference number.
Countdown	`expiresAt` bazlı kalan süre.
CTA	Kullanıcının “ödeme yaptım” aksiyonu.

Önerilen modeller:

Model	Ne zaman?	Not
Full-page redirect	Mobile web veya basit integration	En düşük browser uyumluluk riski.
Popup/new tab	Kullanıcıyı partner siteden tamamen çıkarmamak istiyorsanız	Popup blocker nedeniyle click handler içinde açılmalı.
iframe	Sadece Pientegra ve partner security policy izin veriyorsa	CSP, frame policy ve browser restrictions ayrıca doğrulanmalı.

Production için en güvenli default full-page redirect veya click-triggered popup'tır.

Click-triggered popup

depositButton.addEventListener('click', async () => {
  const popup = window.open('about:blank', '_blank');
  if (!popup) {
    showPopupBlockedMessage();
    return;
  }

  try {
    const response = await fetch('/api/pientegra/deposits', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ amount: '100000' }),
    });

    const body = await response.json();
    popup.location = body.depositUrl;
  } catch (error) {
    popup.close();
    throw error;
  }
});

Partner frontend Pientegra API key'i asla bilmez. Frontend yalnızca partner backend'inize request atar; Pientegra request'i backend'inizden çıkar.

Expiry behavior

depositUrl one-time, signed ve time-limited bir URL'dir. Süre dolarsa kullanıcı expired state görür ve yeni deposit request başlatmalıdır.

Önemli noktalar:

Kullanıcı expired URL ile ödeme yapmamalıdır.
Expiry sonrası para gelirse Pientegra bunu LATE_ARRIVAL olarak işaretleyebilir.
Nihai balance credit sadece intent.approved webhook'u ile yapılmalıdır.

Frontend sorumlulukları

Amount'u backend'e minor unit olarak gönderin.
API key'i frontend'e koymayın.
Popup kullanıyorsanız pencereyi click handler içinde açın.
Kullanıcı deposit page'den döndüğünde bakiyeyi anında varsayımsal artırmayın.
Balance update için webhook sonucu bekleyin.

Backend sorumlulukları

POST /external/deposits request'ini idempotent key ile gönderin.
intentId, referenceNo, depositUrl ve request payload'ını saklayın.
Webhook handler'da intent.approved:<intent.id> gibi business idempotency key kullanın.
Status endpoint'i sadece support/reconciliation için kullanın.

Create Deposit

depositUrl üreten backend endpoint.

Webhook Events

intent.created, intent.approved, intent.rejected ve intent.auto_cancelled event'leri.