Wat is een donatieformulier?
Donatieformulieren bieden een infrastructuur waarmee u donaties kunt ontvangen door ze in uw eigen website te integreren. U kunt een donatieformulier aanmaken door naar het gedeelte Donaties > Donatieformulier in het linkermenu te gaan.
Wat is er veranderd ten opzichte van V1?
Donatieformulieren kunnen nu zowel ingebed als als pop-up op uw site functioneren.
U hoeft geen parameters zoals bedrag, terugkerende donatie, valuta, enz. te verzenden.
De structuur voor resultaatmeldingen (Callback) is gewijzigd van JS naar HTTP POST.
Testen is vereenvoudigd.
Het websiteadres moet als volledig adres worden ingevoerd.
De mogelijkheid om vooraf gedefinieerde bedragsopties aan te bieden is toegevoegd.
Foutmeldingen zijn toegevoegd in de ontwikkelaarsconsole.
Waar moet u op letten bij het aanmaken?
Het belangrijkste punt bij het aanmaken van een donatieformulier is dat u het volledige adres van de website waar u het formulier zult gebruiken, moet invoeren. Bij het invoeren van het adres moet u https:// opnemen. En als uw website meerdere versies heeft, moet u deze uniek maken.
Donatieformulieren werken in een live omgeving alleen met HTTPS. U kunt testen met HTTP in een testomgeving.
Bijvoorbeeld;
https://www.domeinnaam.org/donatie/algemene-donatie
Als uw site werkt als zowel https://www.domeinnaam.org als https://domeinnaam.org, kies dan slechts één en verwijs de niet-gekozen domeinnaam door naar de andere.
Website-integratie
WAARSCHUWING! Deze integratie vereist softwarekennis. U moet bekend zijn met basis HTML en Javascript. Als u hier niet bekend mee bent, gebruik dan onze standaard donatiepagina's.
Ten eerste moet jQuery op uw website geladen zijn. Als jQuery niet geladen is, geeft Fonzip een foutmelding.
Ten tweede, als de Referrer-Policy headerwaarde op uw pagina no-referrer is, zal Fonzip een foutmelding geven. U moet een andere waarde gebruiken dan deze.
U kunt basisintegratie-informatie vinden in het gedeelte Donatie > Donatieformulieren > Acties > Integratie-informatie.
<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>Voeg ons script op deze manier toe aan de pagina.
Als u het betreffende formulier ingebed wilt laten werken, voegt u in het <script> blok:
fzv2("embed", "SLEUTEL", "TE-TOEVOEGEN-ID");Als u het als pop-up wilt laten werken, voegt u in het <script> blok:
fzv2("popup", "SLEUTEL", "KNOP-ID");code toe.
Als u het ingebedde formulier wilt starten, maar het verborgen wilt houden:
fzv2("embed", "SLEUTEL", "TE-TOEVOEGEN-ID", true);
Het is voldoende om de 4e parameter als true te verzenden.
De HTML-tag waaraan het ingebedde formulier moet worden toegevoegd, moet <body>, <div> of <section> zijn.
De HTML-tag die de pop-up moet activeren, moet <button> of <a> zijn.
Donatieformulieren werken automatisch in de browsertaal. Als de lang-parameter is gedefinieerd in het html-blok van uw webpagina, wordt die taal in overweging genomen. Als u een specifieke taal wilt afdwingen, dan voor de embed- en pop-upfuncties:
fzv2("lang", "TAAL")U kunt een taal selecteren op deze manier.
Geldige talen
tr (Turks)
en (Engels)
de (Duits)
fr (Frans)
es (Spaans)
it (Italiaans)
pt (Portugees)
nl (Nederlands)
ru (Russisch)
Gegevensoverdracht naar het formulier
Als u een vooraf gedefinieerde waarde wilt toevoegen aan het pop-upformulier, kunt u de onderstaande attributen aan de betreffende knop toevoegen. Of u kunt op elk moment gegevens overdragen naar elk formulier met de functie "data". U kunt de functie "data" gebruiken door het attribuut "fz-data" te verwijderen. Bijvoorbeeld;
fzv2("data", "embed", "SLEUTEL", "currency", "USD")Attributen | Beschrijving | Waarde |
fz-data-currency | Valuta | ISO 4217 |
fz-data-recurring | Terugkerend / Eenmalig | true|false |
fz-data-amount | Donatiebedrag | Getal |
fz-data-recurring-limit | Tijdelijk terugkerende donatie | 0 - 60 |
fz-data-donor-type | Type donateur | corporate|personal |
fz-data-first-name | Voornaam / Bedrijfsnaam | Alfanumeriek{0,200} |
fz-data-last-name | Achternaam | Alfanumeriek{0,200} |
fz-data-email | E-mail{0,200} | |
fz-data-phone | Telefoon | Telefoon{0,25} |
fz-data-birthday | Geboortedatum | Datum (Dag/Maand/Jaar) |
fz-data-city | Stad | Alfanumeriek{0,200} |
fz-data-district | Wijk | Alfanumeriek{0,200} |
fz-data-address | Adres | Alfanumeriek |
fz-data-tckno | Nationale Identiteitsnummer / Belastingnummer | Nummer{11,13} |
fz-data-details | Details | Alfanumeriek{0,300} |
fz-data-referring | Namens iemand | true|false |
fz-data-referring-name | Persoon namens wie de donatie wordt gedaan | Alfanumeriek{0,100} |
fz-data-referring-email | E-mail van de persoon namens wie de donatie wordt gedaan | E-mail{0,100} |
fz-data-news-via-phone | Toestemming voor communicatie via telefoon | true|false |
fz-data-news-via-sms | Toestemming voor communicatie via SMS | true|false |
fz-data-news-via-email | Toestemming voor communicatie via e-mail | true|false |
fz-data-fundraising-campaign-id | Donatiecampagne | Nummer |
fz-data-name-hidden | Naam verbergen | true|false |
fz-data-amount-visible | Donatiebedrag zichtbaar | true|false |
fz-data-api-tracking-id | API Tracking ID | Alfanumeriek{0,20} |
fz-data-custom-parameters | Aangepaste parameters |
|
Als de toegevoegde attributen het hele formulier invullen, gaat het formulier automatisch verder naar de volgende stappen. Dat wil zeggen, als er bedragsinformatie is, wordt het automatisch doorgestuurd naar het gedeelte met donateurgegevens; en als er donateurgegevens zijn, wordt het direct doorgestuurd naar het gedeelte met kaartgegevens.
Aangepaste parameters
U kunt de functie voor aangepaste parameters gebruiken om elk veld dat niet is gedefinieerd in Fonzip, maar dat u gebruikt bij het ontvangen van donaties, over te dragen naar Fonzip.
Aangepaste parameter aanmaken
U kunt een parameter aanmaken door op de tekst Parameter toevoegen te klikken in het gedeelte Aangepaste Parameters onderaan de pagina voor het aanmaken/bewerken van het donatieformulier.
In het scherm dat verschijnt, voert u de sleutelwaarde die u in de parameter wilt gebruiken in het veld Veldnaam in en de waarde die u in het systeem wilt weergeven in het veld Beschrijving en slaat u op.
Bijvoorbeeld, we hebben een parameter aangemaakt met veldnaam bon en beschrijving Bon aanvraag. Als de donateur daarnaast een bon wil, vullen we dit veld in als "Ja"; als hij geen bon wil, vullen we "Nee" in.
Opmerking: Er zijn geen beperkingen op de waarden die in de parameters kunnen worden doorgegeven.
U moet een JSON-string doorgeven aan het attribuut fz-data-custom-parameters. Voorbeeld:
<button id="fonzip-button" fz-data-custom-parameters="{'bon': 'bon_waarde'}"/>Nadat de donatie is voltooid, als de optie voor een bon is geselecteerd, kunt u de relevante gegevens in de donatiedetails zien, zoals hieronder.
Aangepaste parameterwaarschuwingen
Het verzenden van een parameter die niet is gedefinieerd in de formulierinstellingen, zal leiden tot een fout in het systeem.
Het verzenden van gegevens in een ander formaat dan JSON zal leiden tot een fout in het systeem.
Als u de veldnaam van een eerder toegevoegde parameter wijzigt/verwijdert, kunt u de gegevens in de betreffende donaties verliezen.
Content Security Policy
Als u uw site voor beveiligingsdoeleinden beschermt met CSP, moet u de volgende definities toevoegen.
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
Als u Nonce gebruikt, kunt u de Nonce-waarde definiëren vóór de embed- of popupfunctie als:
fzv2("nonce", "NONCE-WAARDE");U kunt dit als zodanig definiëren.
Resultaat retourmeldingen
Als u geen Resultaat Retour URL definieert bij het aanmaken/bewerken van uw formulier, toont Fonzip het standaard succes-/foutscherm en stuurt het de donateur vervolgens door naar het door u gedefinieerde Pagina-adres.
Als u er wel een heeft gedefinieerd, wordt het resultaat van de transactie als HTTP POST naar de door u gedefinieerde URL gestuurd. U kunt de te verzenden parameters vinden in de onderstaande tabel.
Als er CSRF-beveiliging is tegen POST-verzoeken die naar de door u gedefinieerde URL worden gedaan, moet deze beveiliging worden verwijderd. Als alternatief kunt u de hash-parameter controleren om te verifiëren dat het verzoek van Fonzip afkomstig is. Het wordt sterk aanbevolen om deze controle uit te voeren.
Berekening van de Hash-parameter
Voor de berekening van de hash-parameter worden de conversation_id en Secret Key gehasht met het sha256-algoritme en omgezet naar een hexadecimaal getal.
hash = sha256(conversation_id + Secret Key)
Voorbeeld:
conversation_id = 123456
Secret Key = geheimssleutel
hash = sha256(12345geheimssleutel) = 823b922b1bf0560b383e50e57e265172757d7718a85cd87497820ae1530e44f6
Parameter | Beschrijving |
donation_id | Registratienummer |
donor_type | Type donateur |
name | Naam donateur |
first_name | Voornaam / Bedrijfsnaam |
last_name | Achternaam |
phone | Telefoon |
birthday | Geboortedatum |
city | Stad |
district | Wijk |
address | Adres |
details | Details |
tckno | Nationale Identiteitsnummer / Belastingnummer |
referring | Namens iemand |
referring_name | Persoon namens wie de donatie wordt gedaan |
referring_email | E-mail van de persoon namens wie de donatie wordt gedaan |
recurring | Terugkerend / Eenmalig |
recurring_limit | Tijdelijk terugkerende donatie |
recurring_order_id | Terugkerende Donatie Instructie Nr |
category_id | Donatie Categorie ID |
category | Donatie Categorie |
name_hidden | Naam verbergen |
amount_visible | Donatiebedrag zichtbaar |
custom_parameters | Aangepaste parameters |
donation_form_id | Donatieformulier ID |
donation_form | Donatieformulier |
news_via_phone | Toestemming voor communicatie via telefoon |
news_via_sms | Toestemming voor communicatie via SMS |
news_via_email | Toestemming voor communicatie via e-mail |
lang | Taal |
complete_date | Transactiedatum (ISO 8601) |
amount | Donatiebedrag |
currency | Valuta (ISO 4217) |
ip_address | IP-adres |
payment_status | Betaalstatus
3: Succesvol
5: Mislukt |
payment_method | Betaalmethode
0: Kaart
8: BKM Express
9: iDEAL
10: Betaal met Iyzico |
payment_settings_id | Virtuele POS ID |
api_tracking_id | API Tracking ID |
order_id | Bank Order Nr |
conversation_id | Trace ID |
last_four | Laatste 4 cijfers kaart |
bin_number | Kaart BIN Nummer |
transaction_id | Bank Transactie Nr |
provision_no | Bank Autorisatie Nr |
auth_code | Goedkeuringsnummer |
reference_id | Referentienummer |
error_code | Foutcode |
error_text | Foutmelding |
hash | Hash |
Geavanceerde instellingen
Als u een formulier van uw pagina wilt verwijderen, moet u de functie "destroy" gebruiken.
fzv2("destroy", "popup", "SLEUTEL")
fzv2("destroy", "embed", "SLEUTEL")
Als u een verborgen formulier wilt weergeven, kunt u de functie "show" gebruiken.
fzv2("show", "popup", "SLEUTEL")
fzv2("show", "embed", "SLEUTEL")
Als u een weergegeven formulier wilt verbergen, kunt u de functie "hide" gebruiken.
fzv2("hide", "popup", "SLEUTEL")
fzv2("hide", "embed", "SLEUTEL")
Als u feedback wilt ontvangen wanneer een pop-upformulier wordt gesloten, moet u de functie definiëren die u wilt aanroepen met de functie "callback".
function close_function(SLEUTEL) {
console.log("popup gesloten", SLEUTEL)
}
fzv2("callback", "popup", "SLEUTEL", "close", close_function)
Overgang van V1 naar V2
Maak eerst een donatieformulier aan voor V2. Aangezien het net als voorheen als pop-up zal werken, moet u het op uw pagina starten als:
fzv2("popup", "SLEUTEL", "KNOP-ID");U moet het op deze manier starten.
Voor de pop-up in V1, voordat u fz.bagis() aanroept zonder de parameters voor bedrag, terugkerend en valuta te verzenden, kunt u de gebeurtenissen van deze wijzigingen in bedrag, terugkerend en valuta reflecteren in de attributen die beginnen met fz-data-*.
Bijvoorbeeld, voorheen:
<script>
function doneren() {
var bedrag = document.getElementById("bedrag").value;
var terugkerend = document.getElementById("terugkerend").checked;
fz.bagis({
amount: bedrag,
recurring: terugkerend
//Andere parameters
})
}
</script>
<input id="bedrag" type="number" step="0.01" placeholder="Donatiebedrag"/>
<input id="terugkerend" type="checkbox" />
<label for="terugkerend">Regelmatig doneren</label>
<a onclick="doneren();" href="javascript:;>Doneren</a>
in plaats van waarden zoals deze te nemen en fz.bagis() aan te roepen wanneer op de knop wordt geklikt, moet u de corresponderende waarden reflecteren in de relevante attributen die beginnen met fz-data-*, wanneer deze waarden veranderen. Bijvoorbeeld:
<script>
document.getElementById("bedrag").addEventListener("change", function(event) {
this.setAttribute("fz-data-amount", this.value);
});
document.getElementById("terugkerend").addEventListener("change", function(event) {
this.setAttribute("fz-data-recurring", this.checked);
})
</script>
<input id="bedrag" type="number" step="0.01" placeholder="Donatiebedrag"/>
<input id="terugkerend" type="checkbox" />
<label for="terugkerend">Regelmatig doneren</label>
<a id="fonzip-button" fz-data-amount="" fz-data-recurring="">Doneren</a>