API Reference

Process overview

The typical process when donating is:

Retrieving the Fundable Projects and offer these projects for your customers to donate to

Assuming your customer chooses to donate; upon submission of their order/purchase your merchant software needs to include the donation amount in the total payment on checkout, and record the donation details (project id, amount, currency, and unique transaction reference) in order to guarantee delivery to Footprints Network.

Your website (or out-of-band processor) Authenticates with the API to obtain the access token, and

Submits the donation

There are two main approaches to the flow of this process, the first is the Client-to-Server, where your purchase path contains javascript which instructs the customers browser to request the fundable projects from the Footprints API.

icons made by Freepik from www.flaticon.com

The second approach is for your server to retrieve the projects and render these as a part of the page where the user picks the project and donation amount.

icons made by Freepik from www.flaticon.com

Either way your form submission needs to make note of the project id selected and the amount and currency being donated.

Should your customer cancel their order or purchase, then you can cancel the donation by:

(optional) Maximum number of projects to retrieve. You may receive less projects than this number if there are insufficient fundable projects allocated to your partner account.

mustIncludeProjectId

(optional) The Project Id of a previously selected project. This is useful when the customer has previously selected a project to donated to, but is allowed to edit that step in their checkout/order process.

Authenticate##

In order to submit or cancel a donation your website (or out-of-band processor) needs to authenticate with the API using your partner credentials.

The API implements the OAuth2 password flow and bearer tokens. The username and password provided for your partner account are secret to your organisation and are only to be used when authenticating from server-to-server and never from browser-to-server.

The expires_in is measured in seconds. Once the access token expires, you must authenticate again.

Submit Donation####

Once your customer has indicated their intention to donate and you have taken payment for their order (plus donation), you must submit the donation details to the API so the projects funding target can be adjusted to reflect the new donation and avoid overfunding.

This action requests an OAuth2 bearer token in the Authorization header as this is a secured action.

Duplicate calls to submit donation using the same reference will fail with a 409 status code, indicating that the donation already exists.

Example####

There is no response body to this action. If the server returns with a 204 status code, then the donation was deleted. If the server returns with a 404 status code, then the donation doesn't appear to exist.

Request Throttling####

In order to avoid undue stress on the system from denial-of-service attacks, the system restricts the volume of requests received in quick succession.

On each non-throttled request there are a few additional headers returned from the throttling engine. These headers are: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. The Limit contains the number of requests allowed until the Reset time occurs, the Reset time is a unix timestamp, and the Remaining header is the number of requests remaining before you you are rejected until the reset time.

If you submit too many requests in very quick submission, you may find you hit the request throttling, which means you will receive a response with a 429 status code, and the JSON object:

Once throttled, there is an additional header returned which is Retry-After, and this header is the number of seconds before the request counter resets for your requests.

Reference Documentation####

The API is self documenting, and exposes a UI for seeing the available methods, responses, data structures, status codes, and supports testing the method calls.

You can see each of these methods, including being able to test the public methods, at the reference documentation site: https://testapi.footprintsnetwork.org/docs
For testing of the secured actions, once you have credentials to the testapi.footprintsnetwork.org system, you will need to authenticate first.