Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
271 lines (197 sloc) 11.4 KB

ThirdPartyApp custom donation form for organisations (BETA)

BETA: This is the second draft of this documentation. Please send us feedback at product@betterplace.org. Or via pull request. Thanks!

Introduction

The ThirdPartyApp custom donation form allows a deep integration of the betterplace.org donation process into your organisations web application.

It is meant for organisations that want to develop and maintain a custom donation experience for their donors.

This feature is distinct from our json-API v4 which you can use to fetch data from the betterplace.org platform.

Example Integrations

  • Ablass App, where you can clean your conscience.
  • Tramprennen and Floßrennen (GitHub) is a race where you can support one of the teams.
  • MADAide, where you can donate to mark a specific piece of the football field with your name.
  • Tierheim Berlin, where you can view and donate to specific needs of the project.
  • (Closed) Donatify me, where you can get Edward to do stuff for you.
  • (Closed) Seeds of Kindness 3, where you get a mp3 download link after your donation. Also there is a leader board and referrer-system.

UserFlow

This is a typical user flow when you use the ThirdPartyApp custom donation form for organisations:

  1. A donor visits your web application
  2. You direct the user to your donation area
  3. … and from there to the custom donation form on betterplace.org
  4. The donation takes place on betterplace.org
  5. We redirect the user back to your page and provide callback parameters

Alternative solutions

Before you start considering the ThirdPartyApp custom donation form please make sure to check out the other online donation tools that betterplace.org provides. Especially the integrated donation form (iFrame). For more, please visit the German or English help area.

How to get it

The ThirdPartyApp donation form needs to be set up by betterplace.org.

Please make sure that you can agree to the terms of use below and send us an email with the following information at product@betterplace.org.

We will check your proposal and get back to you. This is a special service in testing and in beta – so no promises!

E-Mail: (all data is required)

* Project url: The URL to your betterplace.org's project.
* Description: A short description of the web application that you plan on building.
* Callback url production: The URL that we redirect users to after a successful donation (see 'How to use it').
* Callback url staging: This is optional. betterplace.org can provide a staging system that uses this staging callback url.
* Contact e-mail: To keep you posted about changes.

Terms of use

This is a special service in testing. Nothing is final or fixed. And it's beta. So don't say we didn't warn you!

  • There is no support from the betterplace.org team for this feature other than this documentation
  • All terms of use and privacy policy of betterplace.org apply
  • We will inform you about changes 7 days ahead via the e-mail address that you provided
  • Should we consider discontinuing this service we will inform you 3 month ahead
  • The code that you write to integrate this donation form in your flow has to be open sourced under Apache License 2.0 for everyones benefit

How to use it

After everything is set up by betterplace.org (see How to get it), you just need to construct the donation form URL and make sure your callback URL can handle the response.

Donation form URL and input parameter

Example:

https://www.betterplace.org/de/projects/480/client_donations/new?client_id=ablass&donation_amount=15&donation_client_reference=wZo2aZCjJHA2CONAXxIQHt
https://www.betterplace.org/ Lets start with the domain
en/, de/ The language for the form
projects/1114/, fundraising-events/seeds-of-kindness-3/ The receiver type and id of the donation.
client_donations/new?client_id=YOUR_APP_ID The path to the donation form. YOUR_APP_ID will be provided by betterplace.org (see How to get it).
&donation_amount=6 OPTIONAL: You can pre-set the donation amount in euro
&donation_amount_readonly=true OPTIONAL: You can specify if the input field for the donation amount (the default or your pre-set amount) should be readonly. This ways users cannot change the amount (easily). –– This feature is not yet implemented!
&donation_client_reference=123 OPTIONAL – but this is basically why you would want to use the ThirdPartyApp donation form in the first place! It allows you to give each donation/donor a unique ID in your application. We will send this ID back to you via the callback url. This way you can track which donation went through. This reference should be url safe, e.g. only consist of alphanumeric symbols like a SHA-1 Hash.
Watch out: This field must be blank or provide a unique identifier. Using the same identifier twice will prohibit donations. Please keep that in mind if you create sharing urls that contain parameters. If you choose to provide a client_reference, you can use this value to look up the donation afterwards (see Handling the post donation).

Please not that the ThirdPartyApp custom donation for does not allow color and layout changes. If you need those, consider using the integrated donation form (iFrame).

Redirect URL and response parameter

This URL is part of the configuration that needs to be done by betterplace.org (see How to get it). We will redirect the donor to this URL after a successful donation. We will also extend the URL with the following reponse parameter.

Cool urls dont change: We cannot change this URL after we created you ThirPartyApp ID. Please consider redirecting inside your application.

Example:

https://www.you-app.cool/callback.php?status=DONATION_COMPLETE&donation_client_reference=wZo2aZCjJHA2CONAXxIQHt
https://www.you-app.cool/callback.php The callback URL you provide
?status=DONATION_COMPLETE The status which tells you all is good. It’s a bit redundant since there is only this one status ;-)
&donation_client_reference=123123 The same value that you provided when opening the donation form via donation_client_reference
&receiver_type=project&receiver_id=1114, &receiver_type=group&receiver_id=seeds-of-kindness-3 The receiver type and id that you specified when opening the form. "FundraisingEvent" stands for "Fundraising Event".
&amount=6 The amount that was actually donated. This corresponts to donation_amount unless the user changed it.
&donation_token=STRING A unique token generated by betterplace.org that identifies this donation in our system. You should store this token in your application (see Handling the post donation).

Handling the post donation

Once you the user clicked on your donation link, there are a number of things that can happen.

Should your application rely on a sum or count of valid donations (for things linke a leader board or a specific way to display a valid donation for example), you need to take care of those things in your application:

User opens the ThirdPartyApp donation form with your client_reference
┣ User donates successfully
┃ ┣ Redirect takes place → Case 1
┃ ┗ Redirect breaks → Case 2
┗ User goes away or donation fails → Case 2

Post donation case 1: Reconcilitian

Szenario: The user donated successfully and the redirect took place.

Result: You receive the DONATION_SUCCESS message via the redirect URL.

You can be sure that the donation was successfully processed and is saved in the betterplace.org database. BUT: There are a few ways that this donation might be canceled again later (by the bank or the user most likely).

Next steps: You need to check for at least 14 days if the donation stays "confirmed".

The donation is (still) valid, if there is an API response with a state:"confirmed" attribute. The donation is invalid if the API response is a 404 (donation_token) or an the search is empty (client_reference).

Usually the state of a donation will only change during the first 14 days. In some cases however the bookback might take place later. Therefore the trigger to check the donations should probably not be time-based but based on the open_amount_in_cents from the projects-json api response. Whenever this number changes whithout you getting new donations, you need to check the reconciliation of all donation.

Post donation case 2: Unknown state

Szenario A: The user does not donate and leaves – for whatever reason. Szenario B: The user donated successfully but the redirect breaks (network connectivity, user cancels request, …).

Result: You don't know nothing about what's going on. Most importantly: You cannot be sure the donation did not take place.

Next steps: Use the client_donations_list API and search for the client_reference that you created once the user clicked on the link to the donation form on your website. You should save the client_refernce for this reason when you generate the link (not just when you receive the callback). You should also wait for at least two minutes before you recheck to give the user time to submit the donation.

Clients of betterplace.org / Whitelabeling

The core for this ThirdPartyApp donation form is the technology that runs our client donation forms. The main difference being, that client donation forms are always whitelabeled to fit the design of the client application. Please get in touch for more information.

Feedback

Please send us feedback at product@betterplace.org