Charity Reporting API

Retrieve Facebook transaction reports programmatically

To learn more about the Fundraiser API, you can visit our Social Good portal: https://socialgood.fb.com/charitable-giving/fundraiser-api

The Charity Reporting API allows you to retrieve your Page's transaction reports programmatically. The data returned is the same found in transaction reports, just in a more convenient JSON format. The list of donations is still grouped by date (meaning that you can only requests donations for a given date or multiple dates) and is returned in chronological order.

How Does it Work

At a high level, these are the steps you may want to implement to call the API:

  1. Generate a non-expiring Page Access Token with the page_read_donations permission.
  2. Use the token to call the endpoints to generate and read transaction reports.
  3. Create a job that runs daily to get the latest report available. At this time, reports are usually available with a two day delay from the date of the donation.
  4. Paginate through all transactions to get all data for a given report
  5. Store the latest date for which you have data and request reports only for new dates.

For more information on transaction reports' availability and data, please refer to the Help Center article.

Generate a Page Access Token

To call the API, you’ll need to use a non-expiring page access token with the page_read_donations permission. Page access tokens are generated via the Facebook Login permission dialog. You can learn about how to generate a page access token from a user access token here: https://developers.facebook.com/docs/pages/getting-started

An admin of the app and charity's Facebook page can use the Graph API Explorer to generate a page access token by selecting the Application from the dropdown list, clicking Get Token, then Get Page Access Token, and following the steps in the dialogs selecting the appropriate charity pages and making sure to select the page_read_donations permission.

Alternatively, you can add a Facebook Login button that requests the page_read_donations permission to your site. The person granting the permission must be an admin of the charity’s Facebook Page for the relevant page to show up in the permission dialog.

The page access token will not expire unless the admin revokes access to your app. More information on page access tokens can be found here: https://developers.facebook.com/docs/pages/access-tokens

Secure your API calls

In the calls below, you’ll notice a field called appsecret_proof. Adding the appsecret_proof parameter adds a level of security by requiring that the call come from your server and requires knowing the app secret. If you're using the official PHP SDK, the appsecret_proof parameter is automatically added.

Although not required to use the API, we also recommend configuring your app to require appsecret_proof in all calls from your app by going to your App Dashboard's Advanced tab and check the Require App Secret option. You can find more information on how to secure your app here: https://developers.facebook.com/docs/graph-api/securing-requests/

Generate the Transaction Report

To trigger the generation of a transaction report, you can make a POST request to /fundraisers/transactions with a page access token.

Field Name Description Type

access_token

A nonprofit Facebook page admin's Page Access Token with page_read_donations permission

string

appsecret_proof

Sha256 hash of the access token using the app secret as the key

string

since

UTC midnight timestamp in seconds of the start time of transactions to receive

int

until

UTC midnight timestamp in seconds of the end time of transactions to receive

int

Example Request

Graph API Explorer
curl -X POST \
  -F 'since=1567814400' \
  -F 'until=1567900800' \
  -F 'appsecret_proof="APPSECRET_PROOF"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/fundraisers/transactions
POST /fundraisers/transactions HTTP/1.1
Host: graph.facebook.com

since=1567814400&until=1567900800&appsecret_proof=APPSECRET_PROOF
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/fundraisers/transactions',
    array (
      'since' => 1567814400,
      'until' => 1567900800,
      'appsecret_proof' => 'APPSECRET_PROOF',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/fundraisers/transactions",
    "POST",
    {
        "since": 1567814400,
        "until": 1567900800,
        "appsecret_proof": "APPSECRET_PROOF"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Response

The response contains the field id, which is the ID of the report to be used in a subsequent GET request.

Example Response

{
  "id":"87654321"
}

Retrieve the Transaction Report

To get the transaction report created by an earlier POST request, make a GET request to /{id}/transactions with a page access token.

Field Name Description Type

access_token

A nonprofit Facebook page admin's Page Access Token with page_read_donations permission

string

appsecret_proof

Sha256 hash of the access token using the app secret as the key

string

Example Request

Graph API Explorer
curl -X GET \
  -d 'appsecret_proof="APPSECRET_PROOF"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{id}/transactions
GET /{id}/transactions?appsecret_proof=APPSECRET_PROOF HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{id}/transactions?appsecret_proof=APPSECRET_PROOF',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{id}/transactions",
    {
        "appsecret_proof": "APPSECRET_PROOF"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Response

The response will contain a list of transaction objects.

This endpoint supports pagination to get the full list of transactions. Learn more about cursor-based pagination here: https://developers.facebook.com/docs/graph-api/using-graph-api/#paging

Field Name Description Type

id

Graph API ID of the transaction object

numeric string

payment_id

Graph API ID of the payment object

numeric string

charge_time

Unix time the transaction occurred

int

charge_date

Date the transaction occurred in YYYY-MM-DD format

string

charge_action_type

Type of charge made S - Normal Charge
R - Refund
C - Chargeback
D - Out of Window Chargebacks
K - Chargeback Reversal
J - Out of Window Chargeback Reversal
N - Decline

string

donation_amount

Transaction amount in cents

int

facebook_fee

The fee Facebook charges, if any, to cover processing the transaction in cents

int

net_payout_amount

Net amount donated to the nonprofit in cents (donation_amount - facebook_fee)

int

payout_currency

ISO 4127 code of donation_amount, facebook_fee, and net_payout_amount

string (ISO 4127)

sender_currency

ISO 4127 code of the currency of the sender

string (ISO 4127)

first_name

First name of the donor

string

last_name

Last name of the donor

string

email

Email of the donor, if provided

string

charity_id

Graph API ID of the charity object

numeric string

fundraiser_id

Graph API ID of the fundraiser object

numeric string

fundraiser_title

Title of the fundraiser

string

fundraiser_owner_name

Name of the owner of the fundraiser

string

permalink_url

URL of the fundraiser on Facebook

string

source_name

Source of the transaction on Facebook

string

The fields below are only available in some countries

gift_aid

If the donation is eligible for Gift Aid

boolean

donor_care_of

Care Of address line of the donor

string

donor_address_line_1

Street address line 1 of the donor

string

donor_address_line_2

Street address line 2 of the donor

string

donor_city

City of the donor

string

donor_state

State of the donor

string

donor_postal_code

Postal code of the donor

string

donor_country

Country of the donor

string

donation_email_for_receipt

Email address for tax purposes, if required

string

donation_country

Donation country for tax purposes, if required

string

Example Response

{
  "data": [
    {
      "payment_id": "123456789123456",
      "charge_time": 1567881064,
      "charge_date": "2019-09-07",
      "charge_action_type": "S",
      "donation_amount": 1224,
      "facebook_fee": 0,
      "net_payout_amount": 1224,
      "payout_currency": "USD",
      "sender_currency": "GBP",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "charity_id": "112233445566778899",
      "fundraiser_id": "998877665544332211",
      "fundraiser_title": "Roger Rabbit's fundraiser to save the world!",
      "fundraiser_owner_name": "Roger Rabbit",
      "permalink_url": "https://www.facebook.com/998877665544332211",
      "source_name": "fundraiser_api",
      "id": "1002003004005"
    },
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUnZA3Y09Ydzg4Tmo3TzdzTnlabF",
      "after": "QVFIUmp6dF9VVlZAERHJHbmRxREhydDW"
    },
    "next": "https://graph.facebook.com/v4.0/*`report_id`*/transactions?after=QVFIUmp6dF9VVlZAERHJHbmRxREhydDW"
  }
}