When we built our Giving Widget, we wanted to make it as portable as possible - everyone in the world should be able to embed one on their website and start raising funds. To ensure that we can trust the source of the donation to be a specific website, we have recently introduced an API endpoint to prepare the donation.
By using the endpoint, we can trust that the donations came from your website. It also provides a way for you to pre-fill the donor details - if you have a login system on your website or intranet, the donors will not have to re-enter their name and email on the widget during the donation process.
This blog post will explain the process and walk you through the example code (PHP, available on GitHub).
How it works
- Your website makes a background request to the API, with some initial data about the donor
- We return you an order ID and some data to sign
- You pass the order ID and a signature directly into the widget as query parameters
- We validate the signature and setup the donation with details
- Once the donation is completed - you can check the order status via the API
- We can also provide you an aggregate report of signed donations - please contact firstname.lastname@example.org
PHP example files
you need to update this and fill in your API key, shared secret and the Giving Widget code you plan to use.
a sample page providing a fake option to log in, to demonstrate how a multi-user system could work.
a sample page providing a fake user profile with an option do donate.
an entry point to the example that deals with user interactions - renders the correct page and calls the library functions to prepare and display the widget.
a library of re-usable functions for dealing with the widget setup endpoint:
parseApiEndpointFromWidgetCode($widgetCode)- given a widget's embed code, returns a correct API URL to be called. See API documentation for details.
setupWidget($endpoint, $apiKey, $donorEmail, $donorFirstName, $donorLastName, $extraInfo)- calls the API endpoint (using PHP's cURL functionality) with donor's details. If you do not know the endpoint URL - you may use
parseApiEndpointFromWidgetCode()to retrieve it from your widget's embed code. Returns an array (dictionary) with the results from the API call (
getOrderSignature($orderId, $salt, $secret)- generates a valid signature for the order that was set up with
getSignedWidgetCode($widgetCode, $orderId, $signature)- updates the widget embed code to include the signed order data, by replacing the widget URL.