Bağış formu nedir?

Bağış formları, kendi web sitenize entegre ederek bağış almanızı sağlayan bir altyapıdır. Soldaki mende bulunan Bağışlar > Bağış Formu bölümüne girerek bir bağış formu oluşturabilirsiniz.

V1'e göre ne değişti?

Bağış formları artık hem sitenize gömülü, hem de popup olarak çalışabiliyor.
Miktar, düzenli bağış, para birimi vs. bir parametre göndermenize gerek yok
Sonuç Bildirim (Callback) yapısı JS'den HTTP POST'a çevirildi
Test etmek kolaylaştırıldı
Web sitesi adresi tam adres olarak girilmeli.
Önden tanımlı miktar seçenekleri sunabilme eklendi
Geliştirici konsolunda hata mesajları eklendi

Oluştururken nelere dikkat etmeli?

Bağış formu oluştururken dikkat edilmesi gereken en önemli nokta formu kullanacağınız web sitesinin tam adresini girmelisiniz. Adresi girerken başında https:// i dahil etmelisiniz. Ve web sitenizin birden çok versiyonu varsa onu tekil hale getirmelisiniz.

Bağış formları canlı ortamda sadece HTTPS ile çalışır. Test ortamında HTTP ile test edebilirsiniz

Örnek olarak;

https://www.alanadi.org/bagis/genel-bagis

Eğer siteniz hem https://www.alanadi.org, hem https://alanadi.org olarak çalışıyorsa lütfen sadece birini seçin ve seçmediğiniz alan adını diğerine yönlendirin.

Web sitesi entegrasyonu

UYARI! Bu entegrasyon yazılım bilgisi gerektirir. Temel HTML ve Javascript'e hakim olmanız gerekir. Eğer bu konulara hakim değilseniz lütfen standart bağış sayfalarımızı kullanın.

İlk olarak web sitenizde mutlaka jQuery yüklü olmalı. Eğer jQuery yüklü değilse Fonzip hata verecektir.

Bağış > Bağış Formları > İşlemler > Entegrasyon Bilgileri bölümünden temel entegrasyon bilgilerine ulaşabilirsiniz.

<script type="text/javascript"> !function(e,t,s,n,c){e.fzv2||(n=e.fzv2=function(){n.callMethod?n.callMethod.apply(n,arguments):n.queue.push(arguments)},e._fzv2||(e._fzv2=n),(n.push=n).loaded=!0,n.version="1.0",n.queue=[],fzv2.script_element=t.createElement(s),fzv2.script_element.async=!0,fzv2.script_element.src="https://s.fonzip.com/js/fzembed.v1.js",(c=t.getElementsByTagName(s)[0]).parentNode.insertBefore(fzv2.script_element,c))}(window,document,"script"); </script>

Şeklinde scriptimizi sayfaya ekleyin.

Eğer ilgili formu gömülü olarak çalıştırmak istiyorsanız <script> bloğunun içine

fzv2("embed", "ANAHTAR", "EKLENECEK-ID");

Eğer popup olarak çalıştırmak istiyorsanız <script> bloğunun içine

fzv2("popup", "ANAHTAR", "BUTON-ID");

Kodunu eklemeniz gerekir.

Gömülü formun ekleneceği HTML etiketi <body>, <div> ya da <section> olmalı.

Popup formun tetikleneceği HTML etiketi <button> ya da <a> olmalı.

Bağış formları otomatik olarak tarayıcı dilinde çalışır. Eğer web sayfanızda html bloğunda lang parametresi tanımlıysa o dili dikkate alır. Eğer siz özel olarak bir dili zorunlu tutmak istiyorsanız embed ve popup fonksiyonlarından önce;

fzv2("lang", "DİL")

Şeklinde dil seçimi yaptırabilirsiniz.

Geçerli diller

tr (Türkçe)
en (İngilizce)
de (Almanca)
fr (Fransızca)
es (İspanyolca)
it (İtalyanca)
pt (Portekizce)
nl (Felemenkçe)
ru (Rusça)

Forma Veri Aktarımı

Eğer popup formuna önceden tanımlı bir değer eklemek istiyorsanız ilgili butona aşağıdaki özellikleri ekleyebilirsiniz. Ya da herhangi bir forma herhangi bir anda "data" fonksiyonu ile veri aktarımı sağlayabilirsiniz. "fz-data" özelliğini çıkartarak "data" fonksiyonunu kullanabilirsiniz. Örnek olarak;

 fzv2("data", "embed", "KEY", "currency", "USD")

Özellikler	Açıklama	Değer
fz-data-currency	Para Birimi	ISO 4217
fz-data-recurring	Düzenli / Tek Seferlik	true\|false
fz-data-amount	Bağış Miktarı	Sayı
fz-data-recurring-limit	Süreli Düzenli Bağış	0 - 60
fz-data-donor-type	Bağışçı Türü	corporate\|personal
fz-data-first-name	Ad / Kurum Adı	Alphanumeric{0,200}
fz-data-last-name	Soyad	Alphanumeric{0,200}
fz-data-email	E-Posta	Email{0,200}
fz-data-phone	Telefon	Phone{0,25}
fz-data-birthday	Doğum Günü	Tarih (Gün/Ay/Yıl)
fz-data-city	İl	Alphanumeric{0,200}
fz-data-district	İlçe	Alphanumeric{0,200}
fz-data-address	Adres	Alphanumeric
fz-data-tckno	TC Kimlik No / Vergi No	Number{11,13}
fz-data-details	Açıklama	Alphanumeric{0,300}
fz-data-referring	Birisi adına	true\|false
fz-data-referring-name	Adına bağış yapılan kişi	Alphanumeric{0,100}
fz-data-referring-email	Adına bağış yapılan kişinin e-postası	Email{0,100}
fz-data-news-via-phone	Telefonla İletişim İzni	true\|false
fz-data-news-via-sms	SMS ile İletişim İzni	true\|false
fz-data-news-via-email	E-Postayla İletişim İzni	true\|false
fz-data-fundraising-campaign-id	Bağış Kampanyası	Number
fz-data-name-hidden	İsmi gözükmesin	true\|false
fz-data-amount-visible	Bağış miktarı gözüksün	true\|false
fz-data-api-tracking-id	API Tracking ID	Alphanumeric{0,20}
fz-data-custom-parameters	Özel Parametreler

Eğer eklenen özellikler bütün formu doldurursa otomatik olarak form sonraki aşamalara ilerler. Yani miktar bilgisi varsa otomatik olarak bağışçı bilgileri bölümüne, bağışçı bilgileri de varsa direk kart bilgileri bölümüne yönlendirilir.

Özel Parametreler

Fonzip'te tanımlı bulunmayan, fakat sizin bağış alırken kullandığınız herhangi bir alanı Fonzip'e aktarmak için özel parametreler özelliğini kullanabilirsiniz.

Özel Parametre Oluşturma

Bağış formunu oluşturma/düzenleme sayfasını en altında bulunan Özel Parametreler bölümünden Parametre ekle yazısına tıklayarak parametre oluşturabilirsiniz.

Karşınıza çıkan ekranda Alan adı bölümüne parametrede geçeceğiniz anahtar değerini, Açıklama bölümüne ise sistemde gözükmesini istediğiniz değeri yazın ve kaydedin.

Örnek olarak alan adı makbuz, açıklaması da Makbuz İsteği alanı adında bir parametre oluşturduk. Eğer bağış yapan kişi ek olarak makbuz istiyorsa bu alanı "Var", eğer makbuz istemiyorsa "Yok" şeklinde dolduracağız.

Not: Parametrelerde geçilecek değerlerde herhangi bir kısıtlama bulunmamaktadır.

fz-data-custom-parameters özelliğine bir JSON string'i geçmeniz gerekir. Örnek

<button id="fonzip-button" fz-data-custom-parameters="{'makbuz': 'makbuz_degeri'}"/>

Bağış tamamlandıktan sonra eğer makbuz isteniyor seçeneği seçildiyse bağış detaylarında aşağıdaki gibi ilgili veriyi görebilirsiniz.

Özel Parametre Uyarıları

Form ayarlarında tanımlanmayan bir parametre gönderilmesi sistemde hata verilmesine sebep olacaktır.
JSON formatı dışında veri gönderilmesi sistemde hata verilmesine sebep olacaktır.
Önceden eklediğiniz bir parametrenin alan adını daha sonradan değiştirdiğinizde/sildiğinizde ilgili bağışlardaki veriyi kaybedebilirsiniz.

Content Security Policy

Eğer güvenlik amaçlı olarak CSP ile sitenizi koruyorsanız aşağıdaki tanımları eklemeniz gerekiyor.

script-src: https://s.fonzip.com
connect-src: https://fonzip.com
style-src: https://s.fonzip.com
img-src: https://s.fonzip.com https://cdn.fonzip.com
frame-src: https://fonzip.com

Eğer Nonce kullanıyorsanız Nonce değerini embed veya popup fonksiyonunda önce

fzv2("nonce", "NONCE-VALUE");

Olarak tanımlayabilirsiniz.

Sonuç Dönüş Bildirimleri

Eğer formunuzu oluşturur/düzenlerken bir Sonuç Dönüş URL tanımlamazsanız Fonzip standart başarılı/başarısız sonuç ekranını gösterir ve sonra bağışçıyı tanımladığınız Sayfa Adresine yönlendirir.

Eğer tanımladıysanız işlem sonucu tanımladığınız URL'e HTTP POST olarak gönderilecektir. Gönderilecek parametreleri aşağıdaki tabloda bulabilirsiniz.

Tanımladığınız URL'de yapılan POST isteklerine karşı CSRF koruması varsa bu korumanın kaldırılması gerekiyor. Buna alternatif olarak isteğin Fonzip'ten geldiğini doğrulamak için hash parametresinde kontrol sağlayabilirsiniz. Bu kontrolü yapmanız şiddetle önerilir.

Hash Parametresinin Hesaplanması

hash parametresinin hesaplanması için sha256 algoritmasıyla conversation_id ve Secret Key hashlenir ve 16 lık tabana çevirilir

hash = sha256(conversation_id + Secret Key)

Örnek:

conversation_id = 123456
Secret Key = gizlianahtar

hash = sha256(12345gizlianahtar) = 823b922b1bf0560b383e50e57e265172757d7718a85cd87497820ae1530e44f6

Parametre	Açıklama
donation_id	Kayıt No
donor_type	Bağışçı Türü
name	Bağışçı Adı Soyadı
first_name	Ad / Kurum Adı
last_name	Soyad
email	E-Posta
phone	Telefon
birthday	Doğum Günü
city	İl
district	İlçe
address	Adres
details	Açıklama
tckno	TC Kimlik No / Vergi No
referring	Birisi adına
referring_name	Adına bağış yapılan kişi
referring_email	Adına bağış yapılan kişinin e-postası
recurring	Düzenli / Tek Seferlik
recurring_limit	Süreli Düzenli Bağış
recurring_order_id	Düzenli Bağış Talimat No
category_id	Bağış Kategorisi ID
category	Bağış Kategorisi
name_hidden	İsmi gözükmesin
amount_visible	Bağış miktarı gözüksün
custom_parameters	Özel Parametreler
donation_form_id	Bağış Formu ID
donation_form	Bağış Formu
news_via_phone	Telefonla İletişim İzni
news_via_sms	SMS ile İletişim İzni
news_via_email	E-Postayla İletişim İzni
lang	Dil
complete_date	İşlem Tarihi (ISO 8601)
amount	Bağış Miktarı
currency	Para Birimi (ISO 4217)
ip_address	IP Adresi
payment_status	Ödeme Durumu 3: Başarılı 5: Başarısız
payment_method	Ödeme Şekli 0: Kart 8: BKM Express 9: iDEAL 10: İyzico ile Öde
payment_settings_id	Sanal POS ID
api_tracking_id	API Tracking ID
order_id	Banka Sipariş No
conversation_id	Trace ID
last_four	Kart Son 4 Hane
bin_number	Kart BIN Numarası
transaction_id	Banka Transaction No
provision_no	Banka Provizyon No
auth_code	Onay Numarası
reference_id	Referans Numarası
error_code	Hata Kodu
error_text	Hata Mesajı
hash	Hash

V1'den V2'ye geçiş

İlk olarak V2 için bir bağış formu oluşturun. Eskisi gibi popup şeklinde çalışacağı için sayfanızda

fzv2("popup", "ANAHTAR", "BUTON-ID");

Şeklinde başlatmanız gerekir.

V1'deki popup'ı fz.bagis() ile miktar, düzenli, para birimi parametrelerini göndermeden önce yapılan işlemleri başlatmadan önce bu miktar, düzenli ve para birimi değişimlerinin olaylarını fz-data-* ile başlayan özelliklere yansıtabilirsiniz.

Örnek olarak eskiden

<script>
function bagis_yap() {
   var miktar = document.getElementById("miktar").value;
   var duzenli = document.getElementById("duzenli").checked;
   fz.bagis({
       amount: miktar,
       recurring: duzenli
       //Diğer parametreler
   })
}
</script>
<input id="miktar" type="number" step="0.01" placeholder="Bağış Miktarı"/>
<input id="duzenli" type="checkbox" />
<label for="duzenli">Düzenli Bağış Yap</label>
<a onclick="bagis_yap();" href="javascript:;>Bağış Yap</a>

gibi değerleri alıp butona tıklanınca fz.bagis() i çağırmak yerine ilgili değerler değişince karşılıklarını fz-data-* ile olan ilgili özelliklere yansıtmanız gerekir. Örnek olarak

<script>
   document.getElementById("miktar").addEventListener("change", function(event) {
    this.setAttribute("fz-data-amount", this.value);
});
   document.getElementById("duzenli").addEventListener("change", function(event) {
    this.setAttribute("fz-data-recurring", this.checked);
})
</script>
<input id="miktar" type="number" step="0.01" placeholder="Bağış Miktarı"/>
<input id="duzenli" type="checkbox" />
<label for="duzenli">Düzenli Bağış Yap</label>
<a id="fonzip-button" fz-data-amount="" fz-data-recurring="">Bağış Yap</a>