What is a Donation Form?
A donation form is an infrastructure that allows you to receive donations by integrating it into your website. You can create a donation form by going to the Donations > Donation Form section on the left menu.
What has changed from V1?
Donation forms can now work both embedded in your site and as pop-ups.
You no longer need to send parameters such as amount, recurring donation, currency, etc.
The result notification (callback) structure has been changed from JS to HTTP POST.
Testing has been made easier.
The website address must be entered as a full address.
The ability to offer predefined amount options has been added.
Error messages have been added to the developer console.
What should you pay attention to when creating it?
The most important point to consider when creating a donation form is to enter the full address of the website where you will use the form. When entering the address, you should include https:// at the beginning. If your website has multiple versions, you should make it singular.
Donation forms only work with HTTPS in live environments. You can test with HTTP in a test environment.
For Example;
https://www.yourdomain.org/donation/donate
If your website works with both https://www.yourdomain.org and https://yourdomain.org, please select only one and redirect the domain you didn't choose to the selected one.
Website integration
WARNING! This integration requires software knowledge. You must be familiar with basic HTML and Javascript. If you are not familiar with these topics, please use our standard donation pages.
First, your website must have jQuery installed. If jQuery is not installed, Fonzip will give an error.
You can access basic integration information from Donations > Donation Forms > Operations > Integration Information section.
<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>Add our script to the page as follows:
If you want to run the relevant form embedded, add the following code inside the <script> block:
fzv2("embed", "KEY", "ELEMENT-ID-TO-EMBED");If you want to run it as a popup, add the following code inside the <script> block:
fzv2("popup", "KEY", "BUTTON-ID");The HTML tag where the embedded form will be added should be <body>, <div>, or <section>.
The HTML tag that will trigger the popup form should be <button> or <a>.
Donation forms automatically work in the browser's language. If the lang parameter is defined in the html block of your web page, it will consider that language. If you want to enforce a specific language, you can do so before the embed and popup functions as follows:
fzv2("lang", "LANGUAGE")Valid languages are
tr (Turkish)
en (English)
de (German)
fr (French)
es (Spanish)
it (Italian)
pt (Portuguese)
nl (Dutch)
ru (Russian)
Data transfer to Forms
If you want to add a predefined value to the popup form, you can add the following properties to the relevant button. Or you can call the "data" function to pass data to any kind of form, any time you want. Remove the "fz-data" attribute for data function. For example;
fzv2("data", "embed", "KEY", "currency", "USD")Attributes | Explanation | Value |
fz-data-currency | Currency | ISO 4217 |
fz-data-recurring | Recurring / One-time | true|false |
fz-data-amount | Donation Amount | Number |
fz-data-recurring-limit | Duration for Recurring Donation | 0 - 60 |
fz-data-donor-type | Donor Type | corporate|personal |
fz-data-first-name | First Name / Company Name | Alphanumeric{0,200} |
fz-data-last-name | Last Name | Alphanumeric{0,200} |
fz-data-email | Email{0,200} | |
fz-data-phone | Phone | Phone{0,25} |
fz-data-birthday | Birthday | Tarih (Gün/Ay/Yıl) |
fz-data-city | City | Alphanumeric{0,200} |
fz-data-district | District | Alphanumeric{0,200} |
fz-data-address | Address | Alphanumeric |
fz-data-tckno | TC ID / Tax ID | Number{11,13} |
fz-data-details | Description | Alphanumeric{0,300} |
fz-data-referring | On Behalf Of | true|false |
fz-data-referring-name | Name of the person on behalf of | Alphanumeric{0,100} |
fz-data-referring-email | Email of the person on behalf of | Email{0,100} |
fz-data-news-via-phone | Permission for Contact via Phone | true|false |
fz-data-news-via-sms | Permission for Contact via SMS | true|false |
fz-data-news-via-email | Permission for Contact via Email | true|false |
fz-data-fundraising-campaign-id | Donation Campaign | Number |
fz-data-name-hidden | Hide Name | true|false |
fz-data-amount-visible | Show Donation Amount | true|false |
fz-data-api-tracking-id | API Tracking ID | Alphanumeric{0,20} |
fz-data-custom-parameters | Custom Parameters | JSON |
If the added features fill out the entire form, the form automatically progresses to the next stages. For example, if there is an amount specified, it automatically moves to the donor information section. If donor information is also provided, it directly proceeds to the payment details section.
Custom Parameters
You can use the Custom Parameters feature to transfer any field that is not defined in Fonzip but is used in your donation process to Fonzip. This allows you to pass additional information that is relevant to your donation workflow but is not part of the standard Fonzip fields.
How to create custom parameter
To create or edit a custom parameter for donation forms, click on the "Add Parameter" link at the bottom of the donation form creation/editing page in the "Custom Parameters" section.
In the window that appears, enter the key value for the parameter in the "Field Name" field and the value you want to display in the system in the "Description" field, then click "Save".
For example, we created a parameter with the field name "receipt" and the description "Receipt Request" in the example. If the donor wants a receipt in addition to the donation, fill in this field as "Yes"; if not, fill it in as "No".
Note: There are no restrictions on the values to be passed in parameters.
You need to pass a JSON string to the fz-data-custom-parameters attribute. Example;
<button id="fonzip-button" fz-data-custom-parameters="{'receipt': 'receipt_value'}"/>After the donation is completed, if the option for a receipt is selected, you can see the relevant information in the donation details.
Warnings for Custom Parameters:
Sending a parameter that is not defined in the form settings will result in an error in the system.
Sending data in a format other than JSON will result in an error in the system.
If you change/delete the field name of a previously added parameter, you may lose the data in the relevant donations.
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.comconnect-src: https://fonzip.comstyle-src: https://s.fonzip.comimg-src: https://s.fonzip.com https://cdn.fonzip.comframe-src: https://fonzip.com
If you are using a nonce, you can define the nonce value before the embed or popup function as follows:
fzv2("nonce", "NONCE-VALUE");Callback URL Notifications
If you do not define a Callback URL while creating/editing your form, Fonzip will display a standard success/failure screen and then redirect the donor to the Page Address you specified.
If you have defined a Callback URL, the result of the transaction will be sent to the URL via HTTP POST. You can find the parameters that will be sent in the table below.
If your Callback URL has CSRF protection, you will need to remove this protection. Alternatively, you can verify that the request came from Fonzip by checking the hash parameter. It is highly recommended to perform this verification.
Calculate Hash Parameter
The hash parameter is calculated by hashing the conversation_id and Secret Key using the sha256 algorithm and converting it to base 16.
hash = sha256(conversation_id + Secret Key)
Example:
conversation_id = 123456Secret Key = gizlianahtarhash = sha256(12345gizlianahtar) = 823b922b1bf0560b383e50e57e265172757d7718a85cd87497820ae1530e44f6
Parameter | Explanation |
donation_id | Record ID |
donor_type | Donor Type |
name | Donor Name Surname |
first_name | First Name / Organization Name |
last_name | Last Name |
phone | Phone |
birthday | Birthday |
city | City |
district | District |
address | Address |
details | Explanation |
tckno | Identity / Tax Number |
referring | In honor of someone |
referring_name | Honoree |
referring_email | Honoree's email address |
recurring | Monthly / One Time |
recurring_limit | Monthly Donation Limit |
recurring_order_id | Monthly Donation Order ID |
category_id | Donation Category ID |
category | Donation Category |
name_hidden | Hide name in donors list |
amount_visible | Display donation amount in donors list |
custom_parameters | Custom Parameters |
donation_form_id | Donation Form ID |
donation_form | Donation Form |
news_via_phone | Can be contacted via Phone |
news_via_sms | Can be contacted via SMS |
news_via_email | Can be contacted via Email |
lang | Language |
complete_date | Transaction Date (ISO 8601) |
amount | Donation Amount |
currency | Currency (ISO 4217) |
ip_address | IP Address |
payment_status | Payment Status
3: Successful
5: Failed |
payment_method | Payment Method
0: Card
8: BKM Express
9: iDEAL
10: Pay with iyzico |
payment_settings_id | Payment System ID |
api_tracking_id | API Tracking ID |
order_id | Order ID |
conversation_id | Trace ID |
last_four | Card Last 4 Number |
bin_number | Card BIN Number |
transaction_id | Transaction ID |
provision_no | Provision No |
auth_code | Approval Number |
reference_id | Reference Number |
error_code | Error Code |
error_text | Error Reason |
hash | Hash |
Migration from V1 to V2
First, create a donation form for V2. Since it will work as a popup, you need to initialize it on your page like this:
fzv2("popup", "KEY", "BUTTON-ID");In V1, before initiating the process with fz.bagis(), you can reflect changes in the donation amount, regularity, and currency to properties starting with fz-data-*.
For example, in V1;
<script>function donate() { var miktar = document.getElementById("amount").value; var duzenli = document.getElementById("recurring").checked; fz.bagis({ amount: amount, recurring: recurring //Other parameters })}</script><input id="amount" type="number" step="0.01" placeholder="Donation Amount"/><input id="recurring" type="checkbox" /><label for="recurring">Monthly Donation</label><a onclick="donate();" href="javascript:;>Donate</a>Rather than calling fz.bagis() when the button is clicked, you should reflect the corresponding values to the relevant properties with fz-data-* when the values change. For example:
<script> document.getElementById("amount").addEventListener("change", function(event) { this.setAttribute("fz-data-amount", this.value);}); document.getElementById("recurring").addEventListener("change", function(event) { this.setAttribute("fz-data-recurring", this.checked);});</script><input id="amount" type="number" step="0.01" placeholder="Donation Amount"/><input id="recurring" type="checkbox" /><label for="recurring">Monthly Donation</label><a id="fonzip-button" fz-data-amount="" fz-data-recurring="">Bağış Yap</a>