With the Form-API you can design a highly individual single- or multi-step donation form for your website just with HTML and Javascript. You don't need knowledge of serverside programming.

We provide you a mighty Javascript-jQuery-Plugin, that takes over a lot of programming work for you, so you can concentrate on designing an awesome donation form without bothering around with validation and payment processing.

Please use a current jQuery-version ( e.g. jQuery 3.6.0 ) and insert our plugin to your code.

❗️
Important
Please use the file directly from our server and do not copy it to your own server. This ensures that the plugin is always up to date.

<script src="path/to/jquery.min.js"></script>
<script src="https://api.fundraisingbox.com/js/jquery.fundraisingbox.min.js"></script>

Now there is a new "fundraisingBoxForm()"-function you can use:

<form id="form"></form>
<script>
$(function() {
    myForm = $("#form").fundraisingBoxForm({
        hash: "{your_form_hash}" // replace {your_form_hash} with your hash without {}-brackets
    });
});
</script>

Authentication

You just have to provide the hash of your form, there is no secret authentication, because the donation form is a public part of your website. You can find the hash of your form in the settings of your form in your FundraisingBox.

🚧
Important note:
The Form-API considers the configuration of the form in your FundraisingBox. So if there are e.g. some required fields, you have to use these fields.

Minimal example form

The following example shows a very simple form to perform a direct debit donation:

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<title>FundraisingBox Example Form</title>
</head>
<body>
	<form id="form">
		<label for="payment_amount">Betrag</label>
		<input type="text" id="payment_amount" name="payment[amount]">
		<div class="error" id="payment_amount_error"></div>
		
		<label for="payment_salutation">Anrede</label>
		<select name="payment[salutation]" id="payment_salutation">
			<option value="" selected="selected">---</option>
			<option value="Mrs.">Frau</option>
			<option value="Mr.">Herr</option>
		</select>
		<div id="payment_salutation_error" class="error"></div>
		
		<label for="payment_first_name">Vorname</label>
		<input type="text" id="payment_first_name" name="payment[first_name]">
		<div class="error" id="payment_first_name_error"></div>
		
		<label for="payment_last_name">Nachname</label>
		<input type="text" id="payment_last_name" name="payment[last_name]">
		<div class="error" id="payment_last_name_error"></div>
		
		<label for="payment_bank_account_owner">Kontoinhaber</label>
		<input type="text" id="payment_last_name" name="payment[bank_account_owner]">
		<div class="error" id="payment_bank_account_owner_error"></div>
		
		<label for="payment_bank_iban">IBAN</label>
		<input type="text" id="payment_last_name" name="payment[bank_iban]">
		<div class="error" id="payment_bank_iban_error"></div>
		
		<input id="submitButton" type="submit" value="jetzt spenden" />
		
		<input type="hidden" name="payment[payment_method]" value="sepa_direct_debit" />
	</form>

	<script src="path/to/jquery.min.js"></script>
	<script src="https://secure.fundraisingbox.com/js/jquery.fundraisingbox.min.js"></script>
	<script>
		$(function() {
			myForm = $("#form").fundraisingBoxForm({
				hash: "{your_form_hash}", // replace {your_form_hash} with your hash without {}-brackets
				successUrl: "https://exampleorga.com/success.html?fbToken=%token%"
			});
		});
	</script>
</body>
</html>

You can see the form live here: https://www.fundraisingbox.com/examples/de/mini.html.

Constructor options

There are several useful options you can use to initialize your form. We recommend to use these options so you don't have to program everything yourself.

Option	Default	Descriptiion
hash		required*: hash of your form
sandboxHash	null	Provide the sandbox hash to force sandbox mode (see Sandbox section)
firstUrl	""	Recommended for multi-step-form: if set, the user will be redirect to this url if user enters a further step directly. Also used to redirect user to first step if user navigates back after successful donation.
nextUrl	""	Required for multi-step-form:* if set, the redirect after submit will go to this url
successUrl	""	Recommended:* If set, the user will be redirected to this page after successful donation, you can use parameters like amount=%amount% etc. to personalize your success page.
failureUrl	""	Recommended:* If set, the user will be redirected to this page after canceling a redirect payment like PayPal.
autoSubmit	true	You can disable the submit-handler if you want to e.g. manipulate or add data before submitting. You can use the doSubmit() function to submit the form manually.
autoRenderErrors	true	After updateSession() or doPayment(): occured errors will be automatically added to the suitable error-divs if they exist.
autoFillValues	true	Currently shown elements are filled with existing values if there is a payment session with already stored data (e.g. for multi-step-form next/back-navigation). See "fillValues()" at Functions.
addSessionHashTo	""	Selector like ".nav a" or jQuery-object. Adds the current session hash to href. See "addSessionHashTo()" at Functions.
autoPayment	true	Call doPayment() if there is no nextUrl set and the session is complete after updateSession().
autoRedirect	true	Redirect to nextUrl if set or to payment provider if redirect payment or to successUrl after successful donation . Warning:* if you set this to "false" you have to handle a returned redirect url (e.g. to PayPal) from doPayment() yourself!
classes	null	You can provide an object with attributes "row", "label", "field-type" and "error" to modify the classes of the default row HTML. See "appendFieldRowsTo()" in Functions for further details.
generalErrorElement	""	Because of Ajax-Validation we recommend to show a general error message to the user in the viewport if errors occured. With this option you can specify the selector (e.g. class or ID) of your error message. The element is shown or hidden automatically.
processingIndicatorElement	""	Because of Ajax-Processing we recommend to show a processing indicator to the user after submitting the form. With this option you can specify the selector (e.g. class or ID) of your indicator. The element is shown or hidden automatically.
creditCardFieldTemplate	"payment_credit_card_owner"	Credit card number and secure id are special fields within iframes. With this option you can specify an ID of a field, from which font stylings are copied to the iframe-fields.
applePayElement	"#fb_payment_method_apple_pay"	Selector for the element(s), that are automatically shown or hidden once it's determined whether Apple Pay is available.
googlePayElement	"#fb_payment_method_google_pay"	Selector for the element(s), that are automatically shown or hidden once it's determined whether Google Pay is available.

Example for generalErrorElement / processingIndicatorElement

The error element is automatically hidden on init and shown if there are errors after submit (if autoRenderErrors is true).
The indicator element is automatically hidden on init and shown after submit. It will be hidden again after the processing is done.

🚧
Recommendation
We strongly recommend to use these features for a better usability for your users.

<form id="form">
  ...
  <input type="submit" value="Spende jetzt" />
  <span class="processing glyphicon glyphicon-hourglass"></span>
  <p id="errorMsg" class="bg-danger text-danger">
    Es sind leider Fehler aufgetreten, bitte überprüfen Sie Ihre Angaben.<br />
    <span id="global_error"></span>
  </p>
</form>
<script>
  ...
  $(function() {
    myForm = $("#form").fundraisingBoxForm({
      hash: "{your_form_hash}", // replace {your_form_hash} with your hash without {}-brackets
      generalErrorElement: "#errorMsg",
      processingIndicatorElement: ".processing"
    });
	});
</script>

Sandbox

In Sandbox mode, only test donations will be created without any charges. Please note that only payment methods which are correctly configured for sandbox mode will be active.
To activate sandbox mode, you only have to provide the form's sandbox hash via the corresponding constructor option (see above) or via a URL parameter. Simply append the parameter sandbox with the hash as its value. Example: example.com/donate.html?sandbox=abcde
When you provide an incorrect sandbox hash, an error is thrown instead of using live mode.

Functions

There are several public functions you can use. Please have a look on the Functions page.

Events

There are several events you can handle, if you want to do some manual work. Please have a look on the Events page.

Exceptions

Exceptions are thrown if there is something wrong that prevents the form to work. You should catch and handle the exceptions.

try
{
  $(function() {
    myForm = $("#form").fundraisingBoxForm({
        hash: "{your_form_hash}" // replace {your_form_hash} with your hash without {}-brackets
    });
	});
}
catch(err)
{
  //TODO e.g. show error to user, mail error to your developer
  if(err.indexOf("maintenance") != -1)
  {
    //... 
  }
}

Possible Exceptions:

Error	Description
error 101: general error error 900: general error	something went wrong, please contact our support
error 102: not owner	you are not allowed to use forms
error 103: inactive	the selected form is inactive
error 104: not api owner	you are not allowed to use the form api
error 105: no hash	form hash is missing
error 106: no config	no form has been found for the given hash
error 107: mismatching sandbox hash	You provided a mismatching sandbox hash - Please omit the sandbox hash to put the form in live mode or provide the correct sandbox hash. (see Sandbox section)
error 201: session incomplete	you can only process complete session with doPayment()
error 202: session processed	processed sessions cannot be read or updated
error 203: session not found	wrong or no session hash at updateSession
error 204: session exists already	hash of existing session used for createSession
error 404: server error error 500: server error	something is wrong with the server
maintenance: ...translated maintenance message...	the FundraisingBox is currently in maintenance mode

📘
Note: HTTP-Code 400
If an error occurs the response has the HTTP-Code 400 and returns a JSON body with more information.

FundraisingBox Link and Logo

🚧
If you are using our Form-API, according to our api terms, you have to show and link our logo on each page. Please use the following code:

<a target="_blank" href="https://www.fundraisingbox.com?utm_source=donation_form"><img border="0" style="border: 0 !important" src="https://secure.fundraisingbox.com/images/FundraisingBox-Logo-Widget.png" alt="FundraisingBox Logo"></a>

More information: API Terms (Paragraph 4.4) and Branding