SupportLogin
Imprint

Requirements and conventions

Please check and consider the Session-API Requirements and conventions. Additionally, if you write your own HTML and use our jQuery-Plugin, following instructions can be helpful.

Please note that new fields can be added in addition to existing fields at any time.

Field names

You have to use the payment-namespace for the name. We also recommend to set the suitable ID.

<input type="text" name="payment[amount]" id="payment_amount" />

Field wrapper

We recommend to use suitable wrapper-divs for better error handling and show/hide-effects.

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

Error handling

You can place and design your errors like you want. If you want to use the automatic error rendering you have to provide an element (e.g. div, span, label, ...) with the required ID (fieldname + "_error") and class ("error"). 

<div class="error" id="payment_amount_error"></div>

The automatic error renderings also adds the "has-error"-class to the coresponding input and wrapper, if they exists.

Example code after auto rendering errors:

<div id="payment_amount_wrapper" class="has-error">
  <label for="payment_amount">Amount</label>
  <input type="text" id="payment_amount" name="payment[amount]" class="has-error">
  <div class="error" id="payment_amount_error">This field is required.</div>
</div>

Global errors
Global errors are special errors not bound to a special field and can occur e.g. after a failed payment or if you submit a field, that's not part of the form (this should be fixed during the development of your form). You should show global errors to the user so he/she can contact you if something went wrong. For automatic error rendering you have to provide an element with "global_error"-class.

<div class="global_error"></div>

🚧

Other fields errors

The Form-API automatically renders existing "other_fields" errors into the "global_errors"-element if there is no next url given. Because in this case some required fields are missing to process the payment.

Covering Transaction Fees

Activate Feature in Form Configuration
Ensure the following fields are included in your form configuration:

  • donor_covers_the_fee (type=checkbox)
  • covered_fee_checksum_amount (type=hidden)
  • amount (type=text|hidden)

These fields are mandatory for seamless integration with the fee coverage feature.

🚧

Important note

The value for covered_fee_checksum_amount must be calculated based on the payment[amount] and the checked state of donor_covers_the_fee. Utilize the getCoverTheFeeResult() method to obtain the necessary values.
For a basic jQuery implementation, refer to the "Helper snippets" section

Adding InputFields to Your Form

If the feature is active in your form configuration but the required input fields are missing, the donation will be created as usual with the flag "Donor covers fee: No."

<form id="form">
<script>
myForm.on("fundraisingBox:init", function () {
  // append fields
  myForm.appendFieldRowsTo("#form", ["amount"]);
  myForm.appendFieldRowsTo("#form", ["donor_covers_the_fee"]);
  myForm.appendFieldTo("#form", ["covered_fee_checksum_amount"]);
});
</script>

Alternatively, you can use custom HTML:

<input type="text" name="payment[amount]" id="payment_amount">

<div id="coverTheFeeField">
  <label for="payment_donor_covers_the_fee">LABEL</label>
  <input type="checkbox" name="payment[donor_covers_the_fee]" id="payment_donor_covers_the_fee">
  <input type="hidden" name="payment[covered_fee_checksum_amount]" id="payment_covered_fee_checksum_amount"></div>
</div>

Displaying Amount Inclusive of Fee

It is recommended to show the amount inclusive of the fee as information to the donor. Obtain the necessary values from the getCoverTheFeeResult() method
For a basic jQuery implementation to update the checkbox label, see our "Helper snippets"

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"><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