/ Tools

API Developers Guide

A technical guide for developers experienced with API's to integrate micro-donations with eCommerce.

The REST API allows you to submit customers donations to their chosen project whilst they are performing an e-commerce transaction on your merchant website.

API Reference

For full reference of each method call, please refer to: http://api.footprintsnetwork.org//docs/index#/

Process overview

The typical process when donating is:

  1. Retrieving the Fundable Projects and offer these projects for your customers to donate to
  2. 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.
  3. Your website (or out-of-band processor) Authenticates with the API to obtain the access token, and
  4. 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.

Client-to-Server Exampleicons 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.

Server-to-Server Exampleicons 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:

  1. Your website (or out-of-band processor) Authenticates with the API to obtain the access token
  2. And Cancels the donation

To get started with the Footprints Network REST API, you will need request a test account to https://testapi.footprintsnetwork.org/docs.

Retrieve Fundable Projects

In order to submit a donation your customer first needs to select the project they wish to donate to.
API Action: GET /v1/partner/{partnerCode}/fundableProjects
URL Template: https://testapi.footprintsnetwork.org/v1/partner/{partnerCode}/fundableProjects?maxProjects={maxProjects}&mustIncludeProjectId={mustIncludeProjectId}&countryCodes={countryCodes}
Headers:

Accept
application/json
_Querystring Parameters:_
partnerCode
(required) Your allocated partner code
maxProjects
(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.
countryCodes
(optional) Comma separated list of ISO3166-1 alpha-3 country codes. This allows the API to target geographically appropriate projects to match your customers interest.

A call to this action can produce different results each time, as the algorithm selects the most appropriate projects based on the projects, your partner account, and the parameters supplied.

This call can either be made by your server or direct from the customers browser.

Example###

curl -X GET --header 'Accept: application/json' \
    'https://testapi.footprintsnetwork.org/v1/partner/wnusa/fundableProjects?maxProjects=1'
[
  {
    "projectId": 159,
    "title": "Save Green Sea Turtles in Bermuda",
    "createdDate": "2016-10-24T01:07:23.79Z",
    "webUrl": {
      "httpUrl": "https://www.footprintsnetwork.org/project/159/Save-Green-Sea-Turtles-in-Bermuda.aspx",
      "httpsUrl": "https://www.footprintsnetwork.org/project/159/Save-Green-Sea-Turtles-in-Bermuda.aspx"
    },
    "fundingCurrencyCode": "USD",
    "country": {
      "id": 28,
      "isoCode": "BMU",
      "name": "Bermuda",
      "webUrl": {
        "httpUrl": "https://www.footprintsnetwork.org/country/28/Bermuda.aspx",
        "httpsUrl": "https://www.footprintsnetwork.org/country/28/Bermuda.aspx"
      }
    },
    "charity": {
      "id": 25,
      "name": "Sea Turtle Conservancy",
      "webUrl": {
        "httpUrl": "https://www.footprintsnetwork.org/partner/25/Sea-Turtle-Conservancy.aspx",
        "httpsUrl": "https://www.footprintsnetwork.org/partner/25/Sea-Turtle-Conservancy.aspx"
      }
    },
    "sector": {
      "id": 9,
      "name": "Environment",
      "webUrl": {
        "httpUrl": "https://www.footprintsnetwork.org/issue/9/Environment.aspx",
        "httpsUrl": "https://www.footprintsnetwork.org/issue/9/Environment.aspx"
      }
    },
    "content": {
      "summary": "This research, conservation and education program is protecting juvenile green turtles that travel to Bermuda to grow up after hatching on nesting beaches around the Caribbean and Latin America.",
      "body": "...",
      "thumbnailImageUrl": {
        "httpUrl": "https://www.footprintsnetwork.org/uploadimages/159_thumb.jpg",
        "httpsUrl": "https://www.footprintsnetwork.org/uploadimages/159_thumb.jpg"
      },
      "mainImageUrl": {
        "httpUrl": "https://www.footprintsnetwork.org/uploadimages/159_hero.jpg",
        "httpsUrl": "https://www.footprintsnetwork.org/uploadimages/159_hero.jpg"
      },
      "charitySmallLogoUrl": {
        "httpUrl": "https://www.footprintsnetwork.org/uploadimages/STC_logo_mini.jpg",
        "httpsUrl": "https://www.footprintsnetwork.org/uploadimages/STC_logo_mini.jpg"
      },
      "charityMediumLogoUrl": {
        "httpUrl": "https://www.footprintsnetwork.org/uploadimages/",
        "httpsUrl": "https://www.footprintsnetwork.org/uploadimages/"
      },
      "charityLargeLogoUrl": {
        "httpUrl": "https://www.footprintsnetwork.org/uploadimages/STC_logo_small.jpg",
        "httpsUrl": "https://www.footprintsnetwork.org/uploadimages/STC_logo_small.jpg"
      },
      "projectImageCaption": "",
      "projectImageCredit": ""
    },
    "fundingStatus": {
      "cost": 20000,
      "amountRaised": 13581.51,
      "donationCount": 5853,
      "asAtDateTime": "2017-03-21T00:40:22.5871147Z"
    }
  }
]

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.

API Action: POST /v1/auth/authenticate
URL Template: https://testapi.footprintsnetwork.org/v1/auth/authenticate
Headers:

Accept
application/json
Content-Type
application/x-www-form-urlencoded

Body Parameters:

grant_type
(required) This must be 'password' for authenticating with credentials.
username
(required) Username for your partner account.
password
(required) Password for your partner account. Passwords ARE case sensitive!
This call can only be made by your server.

Example###

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
    --header 'Accept: application/json' \
    -d 'grant_type=password&username=partnerusername&password=partnerpassword' \
    'https://testapi.footprintsnetwork.org/v1/auth/authenticate'
{
  "access_token": "3zCn...G66w",
  "token_type": "bearer",
  "expires_in": 3599
}

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.

API Action: POST /v1/donations/donation
URL Template: https://testapi.footprintsnetwork.org/v1/donations/donation
Headers:

Accept
application/json
Authorization
bearer xyz...123
Content-Type
application/json
_Body Content:_ The body contains a JSON object with the following properties.
reference
(required) Unique reference for the transaction.
projectId
(required) Identifier of the project, as obtained by Fundable Projects
amount
(required) Decimale amount of the currency
currency
(required) ISO4217 currency code (note: only ARS, AUD, BRL, CAD, CHF, CLP, CNY, CZK, EUR, GBP, IDR, INR, JPY, MTL, MXN, MYR, NOK, NZD, PLN, SEK, SGD, THB, USD, ZAR are supported at this time)
name
(optional) Customers name
email
(optional) Customers email address
This call can only be made by your server using the recently obtained access_token.

Example####

curl -X POST --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer 3zCn...G66w' \
    -d '{ "reference": "reference123", "projectId": 7, "amount": 2, "currency": "AUD", "name": "Mr Test Customer", "email": "test123@merchant.tst" } }' \
    'https://testapi.footprintsnetwork.org/v1/donations/donation'
{
  "reference": "reference123",
  "projectId": 7,
  "amount": 2,
  "currency": "AUD",
  "name": "Mr Test Customer",
  "email": "test123@merchant.tst",
  "donationDate": "2017-03-21T02:17:22.94Z",
  "isCancelled": false
}

Cancel Donation####

If a customer cancels their purchase/order, you can cancel the matching donation using this action.

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

API Action: DELETE /v1/donations/donation
URL Template: https://testapi.footprintsnetwork.org/v1/donations/donation?reference={reference}
Headers:

Accept
application/json
Authorization
bearer xyz...123
_Querystring parameters:_
reference
(required) The unique reference for the original donation.
This call can only be made by your server using the recently obtained access_token.

Example####

curl -X DELETE --header 'Accept: application/json' \
    --header 'Authorization: Bearer 3zCn...G66w' \
    'https://testapi.footprintsnetwork.org/v1/donations/donation?reference=reference123'

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:

{ "message": "Your request count (50) is over the allowed limit of 40" }

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.

  • Go to the Authenticate action in the documentation site
  • Enter your username, password, and the grant_type of 'password' and click "Try it out!"
  • If your credentials were correct, the Response Body will contain a JSON object, of which one property will be access_token.
  • Copy the access_token value, and paste it in the "access_token" field in the header at the top of the page, next to the "Explore" button.
    Access Token In Header
  • Click the "Explore" button.

The secure actions on the page will now be available to try out, as the Authorization header will automatically be added to each request.