You can call these functions on your jQuery-form-object:

🚧
Important note
The form is initialized asynchronously, so you have to handle the init-event, if you want to use these functions. See Events for further information.

myForm = $("#form").fundraisingBoxForm({
  hash: "{your_form_hash}" // replace {your_form_hash} with your hash without {}-brackets
});
myForm.on("fundraisingBox:init", function() {
  var suggestions = myForm.getAmountSuggestions();
  myForm.updateSession();
  ...
});

Config getter functions

These functions provide the configuration of your form, defined by your form settings in your FundraisingBox. Please have a look on the Form Configuration JSON for further details.

getAmountSuggestions()

[
  {
    "amount": "10",
    "description": "Auch eine kleine Spende hilft!"
  },
	{
    "amount": "50",
    "description": "Vielen Dank für diese Spende!"
  },
  ...
]

getItems()

[
  {
    "id" : "1234",
		"title": "Hund 10€",
    "amount": 10,
  	"visible": true,
    "fb_project_id": 123,
    "order": 1
  },
  {
    "id": "5678",
    "title": "Katze 20€",
    "amount": 20,
    "visible": false,
    "fb_project_id": 456,
    "order": 0
  },
  ...
]

getPaymentMethods()

{
  "sepa_direct_debit": {
    "countries": "DE AT CH",
    "amount_min": 0.01,
    "amount_max": 50000,
    "label": "SEPA-Lastschrift",
    "recurring": true
  },
  "stripe_apple_pay": {
    "countries": "",
    "amount_min": 0.5,
    "amount_max": "",
    "label": "Apple Pay",
    "recurring": false,
    "can_make_payment": true // only available after fundraisingBox:walletPayReady event has been triggered
  },
  "stripe_google_pay": {
    "countries": "",
    "amount_min": 0.5,
    "amount_max": "",
    "label": "Google Pay",
    "recurring": false,
    "can_make_payment": false // only available after fundraisingBox:walletPayReady event has been triggered
  }
  ...
}

getFormFields()

{
   "first_name":
   {
      "id": "payment_first_name",
      "label": "Vorname",
      "type": "text",
      "validator":
      {
          "type": "text",
          "required": true,
          "max_length": 100,
          "min_length": 2
      },
      "field_html": "<input maxlength=\"100\" type=\"text\" name=\"payment[first_name]\" id=\"payment_first_name\" />",
      "label_html": "<label for=\"payment_first_name\">Vorname&nbsp;*</label>",
      "error_html": "<div id='payment_first_name_error' class='error'></div>",
      "visible:": true, //optional, only for custom fields
      "hide_mobile": false //optional
   },
   ...
}

Cover The Fee

getDonorCoversTheFee()

Returns a boolean value, specifically true under the following conditions:

The feature is activated in your form configuration.
The checkbox <input type="checkbox" name="payment[donor_covers_the_fee]"> is selected or the value is saved in your paymentSession.

This can be utilized to dynamically assess whether the donor has opted to cover transaction fees in the payment process. The returned true indicates that the feature is active and the fee coverage checkbox is selected.

getCoverTheFeeResult()

Returns the values for cover-the-fee based on the current amount

{
  amount: 50,
  covered_fee: 1.76,
  amount_inclusive_fee: 51.76,
};

getCoverTheFeeResultForAmount(amount: Int)
Returns the values for cover-the-fee based on the specified amount

{
    "amount": 99,
    "covered_fee": 3.13,
    "amount_inclusive_fee": 102.13
}

getCoverTheFeeConfig()
Returns the values for the calculation of CoverTheFeeResult

{
    "fix": 0.36,
    "percentage": 2.8
}

Returns undefined if the feature is deactivated in your form configuration

Contextual getter-functions

getSession()

Returns Session JSON.

getTransaction()

Returns Transaction JSON.
Only available after payment on a success page.

getErrors()

Returns Errors JSON.

getTranslatedValues()

Returns Translated Values JSON.

isSandboxMode()

Returns a boolean value.

View helper functions

These functions can help you to create highly dynamical foms, maintained by the form settings in your FundraisingBox.

target

Can be a css selection string or a jQuery-object

<div id="myAmount"></div>
<div id="myInterval">
  <label>Interval</label>
	<select name="payment[interval]">...</select>
</div>
<script>
  ...
  myForm.appendFieldRowsTo("#myAmount", ["amount"]);
	myInterval = $("#myInterval");
	myForm.appendErrorDivTo(myInterval, "interval");
</script>

addSessionHashTo(target)

Adds the current session hash to the href attribute of the target-elements, e.g. useful for a navigation of a multi-step-form.

📘
Constructor option
You can also use the "addSessionHashTo" constructor option to do this automatically on init.

<ul class="nav">
  <li><a href="1.html">1.Step</a></li>
  <li><a href="2.html?param=true">2.Step</a></li>
</ul>
<script>
  ...
  myForm.addSessionHashTo(".nav a");
</script>

//RESULT:
<ul class="nav">
  <li><a href="1.html?fbSessionHash={your_session_hash}">1.Step</a></li>
  <li><a href="2.html?param=true&fbSessionHash={your_session_hash}">2.Step</a></li>
</ul>

appendFieldRowsTo(target, fieldnames, classes)

Appends to the target a div containing wrapper-divs with label, field and error-div.
fieldnames: optional, array of fieldnames. If undefined, all fields of the form are added to the target. This can be helpful to get a quick overview for a developer.
classes: optional, object with optional "row", "label", field-type ("text", "select", "textarea", "radio", "checkbox", "hidden") and "error" attributes to add certain classes to the elements. If no classes-object is provided, the default classes of the contructor options are used if exist.

📘
AutoFillValues
If the constructor option autoFillValues is true, the fields are automatically filled with the corresponding existing values of the session.

<div id="donationFields"></div>
<div id="personFields"></div>
<script>
  ...
  myForm = $("#form").fundraisingBoxForm({
    hash: "{your_form_hash}",
    classes: {
      row: "myRowClass",
      label: "myLabelClass",
      text: "myInputClass", //for input type text
      textarea: "myTextareaClass",
      select: "mySelectClass myOtherSelectClass",
      radio: "myRadioClass",
      checkbox: "myCheckboxClass",
      error: "myErrorClass"
  });
  myForm.appendFieldRowsTo("#donationFields", ["amount", "interval"]);
  myForm.appendFieldRowsTo("#personFields", ["first_name", "last_name"], {
    row: "nameRowClass",
    text: "nameInputClass"
  });
</script>

// RESULT:
<div id="donationFields">
  <div>
    <div id="payment_amount_wrapper" class="myRowClass">
      <label for="payment_amount" class="myLabelClass">Betrag</label>
      <input type="text" id="payment_amount" name="payment[amount]" class="myInputClass">
      <div class="error myErrorClass" id="payment_amount_error"></div>
    </div>
    <div id="payment_interval_wrapper" class="myRowClass">
      <label for="payment_interval" class="myLabelClass">Rhythmus</label>
      <select id="payment_interval" name="payment[interval]" class="mySelectClass myOtherSelectClass">
        <option value="1">monatlich</option>
        <option value="3">vierteljährlich</option>
        <option value="6">halbjährlich</option>
        <option value="12">jährlich</option>
        <option value="0">einmalig</option>
      </select>
      <div class="error myErrorClass" id="payment_interval_error"></div>
    </div>
  </div>
</div>
<div id="personFields">
  <div>
    <div id="payment_first_name_wrapper" class="nameRowClass">
      <label for="payment_first_name">Vorname</label>
      <input type="text" id="payment_first_name" name="payment[first_name]" class="nameInputClass">
      <div class="error" id="payment_first_name_error"></div>
    </div>
    <div id="payment_last_name_wrapper" class="nameRowClass">
      <label for="payment_last_name">Nachname</label>
      <input type="text" id="payment_last_name" name="payment[last_name]" class="nameInputClass">
      <div class="error" id="payment_last_name_error"></div>
    </div>
  </div>
</div>

appendFieldTo(target, fieldname, class)

Appends to the target the default field HTML.
class: optional class string. If not provided, the default class of the contructor options is used if exists.

📘
AutoFillValues
If the constructor option autoFillValues is true, the field is automatically filled with the corresponding existing value of the session.

<label for="payment_first_name">What is your first name?</label>
<div id="myFirstName"></div>
<script>
  ...
  myForm.appendFieldTo("#myFirstName", "first_name", "myFieldClass");
</script>

//RESULT
<label for="payment_first_name">What is your first name?</label>
<div id="myFirstName">
  <input maxlength="100" type="text" name="payment[first_name]" id="payment_first_name" class="myFieldClass" />
</div>

appendLabelTo(target, fieldname, class)

Appends to the target the default label HTML.
The default label contains  , required-asterisk and possibly links (terms and privacy label).
class: optional class string. If not provided, the default class of the contructor options is used if exists.

<div id="myFirstNameLabel"></div>
<input type="text" name="payment[first_name]" id="payment_first_name" />
<script>
  ...
  myForm.appendLabelTo("#myFirstNameLabel", "first_name", "myLabelClass");
</script>

//RESULT
<div id="myFirstNameLabel">
  <label for="payment_first_name" class="myLabelClass">Vorname&nbsp;*</label>
</div>
<input type="text" name="payment[first_name]" id="payment_first_name" />

appendErrorDivTo(target, fieldname, class)

Appends to the target the default error div HTML, required for automatic error rendering.
class: optional class string. If not provided, the default class of the contructor options is used if exists.

<label for="payment_first_name">What is your first name?</label>
<input type="text" name="payment[first_name]" id="payment_first_name" />
<div id="myFirstNameError"></div>
<script>
  ...
  myForm.appendErrorDivTo("#myFirstNameError", "first_name", "myErrorClass");
</script>

//RESULT
<label for="payment_first_name">What is your first name?</label>
<input type="text" name="payment[first_name]" id="payment_first_name" />
<div id="myFirstNameError">
  <div id="payment_first_name_error" class="error myErrorClass"></div>
</div>

getLabelString(fieldname)

Returns the cleaned string of the label. There are no HTML-entities, asterisk and links.
For example "Vorname" instead of Vorname *

<label id="myLabel" for="payment_first_name"></label>
<script>
  ...
	$("#myLabel").html("Wie ist dein "+myForm.getLabelString("first_name")+"?");
</script>

//RESULT
<label for="payment_first_name">Wie ist dein Vorname?</label>

renderErrors()

First removes all currently visible errors in the form:

searches for ".error" classes and deletes the content
removes ".has-error" classes from wrapper-divs and inputs

Then adds the "current_fields"-errors of the session to the corresponding error-divs and adds ".has-error" class to corresponding wrapper-divs and inputs.
If a generalErrorElement is defined in the constructor options, this element will be shown.
If nextUrl is empty: adds also the "other_fields"-errors and "globals"-errors to the div with the ID "global_error".

📘
Constructor option
This function is called automatically if constructor option "autoRenderErrors" is true.

<div id="payment_amount_wrapper">
  <label for="payment_amount">Betrag</label>
  <input type="text" id="payment_amount" name="payment[amount]">
  <div class="error" id="payment_amount_error"></div>
</div>

<script>
  ...
  myForm.renderErrors();
</script>

//RESULT:
<div id="payment_amount_wrapper" class="has-error">
  <label for="payment_amount">Betrag</label>
  <input type="text" id="payment_amount" name="payment[amount]" class="has-error">
  <div class="error" id="payment_amount_error">Dies ist ein Pflichtfeld.</div>
</div>

fillValues()

Fills the exisiting form-fields with the corresponding values stored in the current session, considering the difference between checkboxes, radio-buttons, inputs and selects.

Additionally:
Replaces also all corresponding {{variables}} with the translated values in all elements with the class "replace_vars". This is very helpful e.g. for a confirmation overview page or to personalize the form steps. You have to use the available keys of the Translated Values JSON. For example {{amount}} or {{first_name}}.

📘
Constructor option
This function is called automatically if constructor option "autoFillValues" is true.

🚧
replace_vars class
We strongly recommend to set this class only where it's necessary. The fillValues-function performs a HTML replace, so if there are elements with e.g. click-observers, these observers are gone after the replace!

<input type="text" name="payment[amount]" />
<input type="text" name="payment[interval]" />
<input type="text" name="payment[fb_item_id]" />
<p class="replace_vars">
  Ich spende {{interval}} {{amount}} € für {{fb_item_id}}.
</p>
<scrip>
  ...
  myForm.fillValues();
</script>

//RESULT:
<input type="text" name="payment[amount]" value="12.5" />
<input type="text" name="payment[interval]" value="1" />
<input type="text" name="payment[fb_item_id]" value="123" />
<p class="replace_vars">
  Ich spende monatlich 12,50 € für Bedrohte Tiere.
</p>

bankAccountReset()

Resets the bank fields to empty value. Useful on payment method change.

<input type="text" name="payment[bank_iban]" value="DE123456..." />
<input type="text" name="payment[bank_bic]" value="AUGSDE..." />
<script>
  ...
  $("[name='payment[payment_method]']").change(function() {
    if($(this).val() != "sepa_direct_debit")
    {
      myForm.bankAccountReset();
    }
  });
</script>

//RESULT:
<input type="text" name="payment[bank_iban]" value="" />
<input type="text" name="payment[bank_bic]" value="" />

doSubmit()

You can call the internal submit-function manually. This function triggers creditCardMakeToken(), updateSession() or doPayment() depending on the selected payment method and current form state. Very useful if autoSubmit-Option is false.

<script>
  myForm = $("#form").fundraisingBoxForm({
    hash: "{your_form_hash}",
    autoSubmit: false
  });
  ...
  myForm.submit(function(event) {
    event.preventDefault();
    // do some stuff here e.g.:
    if(confirm("Submit form now?"))
    {
      myForm.doSubmit();
    }
    return false;
  });
</script>

API endpoint functions

updateSession()

Retrieves the values of the current form and sends it to the app/createSession-endpoint or app/updateSession-endpoint.
Triggers the event fundraisingBox:updateSession after successful api call.
If autoRenderErrors: triggers renderErrors() if there are errors.
If autoRedirect and nextUrl: redirects to nextUrl with appended session_hash-parameter.
If autoPayment: triggers doPayment() if there are no errors and no nextUrl.

doPayment()

Sends the current session to the app/payment-endpoint.
Triggers the event fundraisingBox:payment after successful api call.
If autoRenderErrors: triggers renderErrors() if there are errors.
If autoRedirect: redirects to the returned redirect_url.

🚧
Warning: autoRedirect false
If you set autoRedirect to "false" you have to handle a returned redirect url (e.g. to PayPal) from doPayment() yourself!

Credit card functions

Credit card fields are special fields in iframes. They need a special treatment of styling and cannot be manipulated directly.

🚧
Important note:
These functions work only after the event fundraisingBox:creditCardReady has been triggered!

creditCardStyle(css)

Sets the style of the inputs. We recommend to do minimal styling to the iframe-inputs and do the main styling on the surrounding div.
Hint: for security reasons custom fonts are not possible.

myForm.on("fundraisingBox:creditCardReady", function() {
  myForm.creditCardStyle("color: #00F; font-size: 14px;");
});

creditCardCopyStyleFromTemplate()

Copies the current font styles (and height if micropayment credit card) from the defined "creditCardFieldTemplate" (default "payment_credit_card_owner") to the secure credit card fields. This function is called initially and on every windows resize. You can call this function manually, e.g. if you've changed the style dynamically or when you toggle the div with the credit cards inputs.

$("#payment_payment_method").change(function() {
  if($(this).val() == "micropayment_credit_card")
  {
    $("#creditCardFields").show();
    myForm.creditCardCopyStyleFromTemplate();
  }
});

creditCardReset()

Resets and shows the iframe-inputs and hides the readonly-fields. This function should be used if the payment_method is changed to another method than credit card.

$("#payment_payment_method").change(function() {
  if($(this).val() != "micropayment_credit_card")
  {
    myForm.creditCardReset();
  }
});

creditCardMakeToken()

This function is automatically called if autoSubmit is active and payment_method is credit card. So in general you do not need to call this action by yourself. Removes possibly existing errors on the credit card fields, sends and validates the credit card data to the payment provider.

On success:

fills the payment_credit_card_token-field with the retrieved token
shows and fills the readonly-fields with the obfuscated credit card data
hides the iframe-inputs
triggers the event fundraisingBox:creditCardSuccess
if autoSubmit: triggers doPayment() or updateSession()

On failure:

retrieves the errors
if autoRenderErrors: triggers renderErrors()
triggers the event fundraisingBox:creditCardError

🚧Important note

Config getter functions

getAmountSuggestions()

getItems()

getPaymentMethods()

getFormFields()

Cover The Fee

getDonorCoversTheFee()

getCoverTheFeeResult()

Contextual getter-functions

getSession()

getTransaction()

getErrors()

getTranslatedValues()

isSandboxMode()

View helper functions

target

addSessionHashTo(target)

📘Constructor option

appendFieldRowsTo(target, fieldnames, classes)

📘AutoFillValues

appendFieldTo(target, fieldname, class)

📘AutoFillValues

appendLabelTo(target, fieldname, class)

appendErrorDivTo(target, fieldname, class)

getLabelString(fieldname)

renderErrors()

📘Constructor option

fillValues()

📘Constructor option

🚧replace_vars class

bankAccountReset()

doSubmit()

API endpoint functions

updateSession()

doPayment()

🚧Warning: autoRedirect false

Credit card functions

🚧Important note:

creditCardStyle(css)

creditCardCopyStyleFromTemplate()

creditCardReset()

creditCardMakeToken()

🚧
Important note

📘
Constructor option

📘
AutoFillValues

📘
AutoFillValues

📘
Constructor option

📘
Constructor option

🚧
replace_vars class

🚧
Warning: autoRedirect false

🚧
Important note: