Charitable Donations API

Documentation

 

Charity Search API – DEPRECATED

Nonprofit Search is a public search API for Nonprofits (National Chapters) which FirstGiving can process donations for. Transport is HTTP with queries defined as GET parameters.  The service is able to respond with JSON and JSONP. The production graph service can be found at: http://graphapi.firstgiving.com/graph/charity?{args}

Arguments
The following attributes are supported.

Search
Multiple attributes can be specified, they will be logically AND’ed.  Attributes marked with ‘weighted’ will be OR’ed, with higher ‘weighted’ results appearing within the first results. Results without mission statements are viewed as lower quality matches and are offset in relevance by -1

  • namestart – Charity names *starting with* this value (weighted 3)
  • namepartial – Charity names including this value (weighted 2)
  • charity_uuid – Public facing Charity UUID
  • ein – Employer Identification Numbe
  • primary_name – Name of the Charity
  • city – Charity location
  • state    – 2 Character State Code.
  • zip – 5 digit location zipcode
  • zip_radius – Number of miles radius to search vs supplied zip
  • ntee – NTEE (National Taxonomy of Exempt Entities) Code.  Either an exact match, or, because there are no Charities assigned parent categories (‘A’ for example) then all matches vs subcategory will be returned.
  • ntee_keyword – partially matches against NTEE keyword, description or name (weighted 1).  If ntee_keyword can not be matched then it is *ignored*.

Page control

  • page_size – dictates the size of the page to return.  Min 1, Max 100 inclusive.
  • page – page number to request

Misc

  • compact – Returns charity_uuid, primary_name, mission_statement, ntee (code), ntee_title by default
  • ret – Returns a single attribute only for the given query.  Similar to ‘compact’ but for a single attribute.
  • callback – Padding callback to add to a JSONP request.  Compatible with jQuery jsonp $.ajax() call.
  • mypostcode – Returns a best guess of the remote hosts zip code.  If a Zip cannot be derived then an empty Zip will be returned.

Service Response
The service returns JSON for the format : Successful responses are delivered with ”’HTTP 200”’ status. payload: total: {results_total_count}, page: {page_number}, num_pages : {Math.ceil(total / page_size)}, num_results: {num_results_returned}, page_size: {size_of_page}, results : {list_of_results} Errors will return as ”’HTTP 404”’. ‘payload’ details the error message.

Examples
”’Get a charity by uuid (compact) ”’ http://graphapi.firstgiving.com/graph/charity?charity_uuid=b6487352-edd0-11df-ab8c-4061860da51d&compact=1 response mime: application/json {“payload”:{“results”:[{“charity_uuid”:”b6487352-edd0-11df-ab8c-4061860da51d”,”primary_name”:”AM FRIENDS OF THE MERAV FOUNDATION II KEREN MERAV”,”mission_statement”:””,”ntee”:”P84″}]}} ”’Get the EIN of a Charity”’ http://graphapi.firstgiving.com/graph/charity?charity_uuid=bbd4a0e8-edd0-11df-ab8c-4061860da51d&ret=ein response mime: application/json {“payload”:{“results”:[{“ein”:”911189441″}]}} ”’JSONP request of all Charities starting with Grayhawk”’ http://graphapi.firstgiving.com/graph/charity?namestart=grayhawk&compact=1&callback=myFunc response mime: text/html myFunc({“payload”:{“results”:[{“charity_uuid”:”b791f350-edd0-11df-ab8c-4061860da51d”,”primary_name”:”GRAYHAWK CLASSIC RESIDENTS FOUNDATION”,”mission_statement”:””,”ntee”:”P20″,”ntee_title”:”Human Service Organizations”}]}}); Example of a complete (not compact) record: { charity_uuid: “b65a7228-edd0-11df-ab8c-4061860da51d” ein: “943295968″ primary_name: “ASIAN PACIFIC ISLANDER CULTURAL CENTER” city: “SAN FRANCISCO” state: “CA” zip: “94103″ ntee: “A20″ mission_statement: “Cultural Center” ntee_data: { description: “Organizations that promote, produce or provide access to a variety of arts experiences encompassing the visual, media or performing arts.” keywords: “Arts Centers; Arts Guilds; Cultural Centers; Multipurpose Arts; Multipurpose Cultural Organizations;” ntee_code: “A20″ title: “Arts & Culture” } } ”’Get My Postcode”’ http://graphapi.firstgiving.com/graph/charity?mypostcode response mime: application/json {“payload”:{“zip”:”94601″}}

NTEE Codes
Below is a list of top level NTEE category codes.  Each code has a number of subcategories contained within, a complete list of these subcategories are available by request. ntee_code    title A    Arts, Culture & Humanities B    Education C    Environment D    Animal-Related E    Health Care F    Mental Health & Crisis Intervention G    Voluntary Health Associations & Medical Disciplines H    Medical Research I    Crime & Legal-Related J    Employment K    Food, Agriculture, Nutrition L    Housing & Shelter M    Public Safety, Disaster Preparedness & Relief N    Recreation & Sports O    Youth Development P    Human Services Q    International, Foreign Affairs R    Civil Rights, Social Action & Advocacy S    Community Improvement & Capacity Building T    Philanthropy, Voluntarism & Grantmaking Foundations U    Science & Technology V    Social Science W    Public & Societal Benefit z    Religion-Related Y    Mutual & Membership Benefit Z    Unknown Extrnal link : [http://www.nccsdataweb.urban.org/PubApps/nteeSearch.php?gQry=allMajor&codeType=NTEE]

Charity Search API – v1.0

Charity Search is a public search API for Nonprofits (National Chapters) which FirstGiving can process donations for. Transport is HTTP with queries defined as GET parameters.  The service is able to respond in both XML and JSON(p) by setting the ‘Accept‘ request header as ‘application/xml‘ and ‘application/json‘ respectively.  If no Accept header is provided, the system will default to XML.  For JSONP response types, append the GET parameter ‘jsonpfunc’ with the value being the padding function name, e.g. :?jsonpFunc=yourJSCallbackFunction. When the jsonpfunc parameter is provided, the response will always default to JSONP output regardless of the value of any accept header.

JSONP Example Usage

Here is an example of using jQuery to make a JSONP call to the graph API:

varparams={
	q:'government_id:752763287',
};
$.ajax({
	dataType:'jsonp',
	contentType:'application/json',
	data:params,
	jsonp:'jsonpfunc',
	url:'http://graphapi.firstgiving.com/v1/list/organization?jsonpfunc=?',
	success:function(data){
		console.log(data.payload[0].organization_name);},
	error:function(error){
        }
});


What’s in a Charity Record?

Field Name Description
organization_uuid Universal ID
organization_name Common Name
organization_alias Alias Name
government_id Government Charity Id (EIN/Registered Charity Id etc)
address_line_1 Address Line 1
address_line_2 Address Line 2
address_line_3 Address Line 2
address_line_full Address normalised for search, system generated if not supplied
city City
region Region
postal_code default Postal/Zip Code
country ISO 3166-1 2 character Country Code
address_full Completed Address normalised for search, system generated if not supplied
phone_number Local phone number
url Organization Home Page
category_code Categorization Code for Tax purposes (NTEE for example)
latitude Address Latitude
longitude Address Longitude

Retrieving a Charity by EIN

Charity objects can be retrieved via GET request to http://graphapi.firstgiving.com/v1/list/organization?q=government_id:{ein}

Request

GET http://graphapi.firstgiving.com/v1/list/organization?q=government_id:260046127 HTTP/1.1
Accept-Encoding: gzip,deflate
Accept: application/json
User-Agent:JakartaCommons-HttpClient/3.1
Host: graphapi.firstgiving.com


Response (JSON expanded for readability)

{
   "payload":[
      {
          "organization_uuid":"b62c2436-edd0-11df-ab8c-4061860da51d",
          "organization_name":"1 1 1 ONE","organization_alias":null,
          "government_id":"260046127",
          "address_line_1":"190 N 10TH ST STE 303",
          "address_line_2":null,  
          "address_line_3":null,
          "address_line_full":null,
          "city":"BROOKLYN",
          "region":"NY",
          "postal_code":"11211-9318", 
          "county":"NY",
          "country":"US",
          "address_full":"190 N 10TH ST STE 303 BROOKLYN NY 11211-9318",
          "phone_number":null,
          "area_code":null,
          "url":null,
          "category_code":"V20",
          "latitude":"40.6594",
          "longitude":"-73.9625",
          "revoked":"0"
      }
   ]
}

 

Searching for Records by Organization Name

The list endpoint can also be used to retrieve find charity records by name. It supports both exact name matching and partial or “name start” functionality. An exact match query takes the form of: http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:{organization name} Partial name search queries can be made by appending an asterisk ‘*’ to the end of the name: http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:{organization name}*

http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:humane%20society&jsonpfunc=wrapper

http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:bat*&jsonpfunc=wrapper

 

Special Characters

Some special characters in name searches may need to be encoded before being sent. For instance, ampersands (&) should be encoded as %26 otherwise it will be interpreted as a query parameter separator rather than part of a name search.

Country Constraints

The graph database contains charity organization data taken from multiple countries including US, Canada, and UK data sources. It is possible to constrain lookups to a single locale by including an additional country parameter in the query: http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:{organization name}* AND country:{country code} For example:

http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:bat*%20AND%20country:US&jsonpfunc=wrapper

Pagination

For partial match queries the maximum number of records that will be returned in a single response is limited to no more than 100. It is possible to control both the size of the result set and the page of results by passing additional parameters in the request.

  • page: specify the page number to return
  • page_size: the maximum number of records to be included in each response (must be smaller than 100)

For example, to get the third page of results 10 records at a time for a partial name search of US charities starting with the name ‘Bat’, the query would look like: http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:bat*%20AND%20country:US&page_size=10&page=3

Counting Records

By appending the parameter named ‘count’ with a value of ‘on’, the response will provide a count of the total number of records rather than any actual records. The count parameter is incompatible with the page and page_size parameters. Example:

http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:bat*%20AND%20country:US&count=on

 

Custom Query Separators

The list query method uses the word ‘AND’ as the default separator, making it impossible to use that word in organization_name searches. It is possible to override the default separator and specify your own by including the ‘sep’ parameter. Example:

http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:american%20AND%20african*%20XZSY%20country:US&sep=XZSY

Listing by ID

In order to return only a list of organization UUID’s for a search instead of entire records, use the ‘list_by_id’ parameter with a value of ‘on’. Example:

http://graphapi.firstgiving.com/v1/list/organization?q=organization_name:bat*%20AND%20country:US&list_by_id=on

Retrieving a Charity by ID

A charity object can be retrieved via a GET request to http://graphapi.firstgiving.com/v1/object/organization/{organization uuid}

Request

GET http://graphapi.firstgiving.com/v1/object/organization/b62c2436-edd0-11df-ab8c-4061860da51d?jsonpfunc=wrapper HTTP/1.1
Accept-Encoding: gzip,deflate
Accept: application/json
User-Agent:JakartaCommons-HttpClient/3.1
Host: graphapi.firstgiving.com


Response (JSON expanded for readability)

wrapper({
    "payload":{
        "organization_uuid":"b62c2436-edd0-11df-ab8c-4061860da51d",
        "organization_name":"1 1 1 ONE",
        "organization_alias":null,
        "government_id":"260046127",
        "address_line_1":"190 N 10TH ST STE 303",
        "address_line_2":null,
        "address_line_3":null,
        "address_line_full":"190 N 10TH ST STE 303",
        "city":"BROOKLYN",
        "region":"NY",
        "postal_code":"11211-9318",
        "county":"NY","country":"US",
        "address_full":"190 N 10TH ST STE 303 BROOKLYN NY 11211-9318",
        "phone_number":null,
        "area_code":null,
        "url":null,
        "category_code":"V20",
        "latitude":"40.6594",
        "longitude":"-73.9625",
        "revoked":"0"
     }
});

HTTP Response Codes

  • 200 OK : Operation completed OK
  • 201 Created : Entity created (POST only).  Payload is an ‘id’ field, eg {“id”:”086533e6-500f-11e0-a56b-4061860da51d”}
  • 400 Bad Request : Unexpected fields or supplied fields did not validate correctly.  Confirm documentation for this API version and retry the request.
  • 403 Forbidden : Client has not been authorized ot the requested API, Method or Object.
  • 404 Not Found : Auth is OK but the requested method or object could not be found.
  • 409 Conflict : The object requested for creation already exists and is active
  • 500 Internal Server Error : A programmatic error was encountered and the issue has been reported internally to the development team.

Try It




Disbursement Only

Send a csv file based on the details below to finance@firstgiving.com. You can use your name/email in most of the fields if you do not have a donor’s name. Send a payment to FirstGiving via Wire Transfer or ACH payment. We will disburse payments with our scheduled payments weekly for charities setup for ACH, monthly (on or about the 15th) for charities that are paid by check.

CSV File Format

File should be CSV formatted as:

  • Column 1 – TransactionId (Required) String. 100 Character limit This must be a unique identifier of the transaction for this Partner For example, this can be the Payment Gateway’s transaction Id Alternatively, it can be anything that uniquely identified this transaction for this Partner Examples: 123, T123, 4cc8b939a6c7a887658595
  • Column 2 – CharityEin (Required) String The IRS supplied charity identification number (e.g. 53-0196605)
  • Column 3 – DonationAmount (Required) Decimal The amount of currency that billing gateway reports as having been successfully captured
  • Column 4 – DonorEmailAddress (Required) String The donor or Partner’s email address
  • Column 5 – DonorFirstName (Required) String The donor’s first name or Partner’s Name
  • Column 6 – DonorLastName (Optional) String The donor’s last name if available
  • Column 7 – DonorTitle (Optional) String The donor’s last name; The proper title for this donor such as ‘Mr.’, or ‘Ms.’.
  • Column 8 – DonorAddressLine1 (Required) String The donor or Partner’s billing address line 1
  • Column 9 – DonorAddressLine2 (Optional) String The donor or Partner’s billing address line 2 if applicable
  • Column 10 – DonorCity (Required) String The donor or Partner’s billing address city
  • Column 11 – DonorState (Required) String The donor or Partner’s billing state code (e.g. NY, MA)
  • Column 12 – DonorCountry (Required) String The donor or Partner’s billing address country code (e.g. US)
  • Column 13 – DonorPostcode (Required) String The billing postal code of the donor or Partner’s address
  • Column 14 – CreditCardType (Optional) String 2-digit string identifier indicating the type of credit card used such as ‘VI’ and ‘MC’
  • Column 15 – CreditCardLast4Digits (Optional) String Last 4-digits of credit card used with donation
  • Column 16 – ApiKey (Required) String Identifies the API key. Example: 8AA276C3-7E57-4CC0-ACE2-9E3FF2BDC58B
Donation Button Callbacks

The integrated donation button supports the injection of variables into the initial donation form via the   FG_DONATE_BUTTON_PARAMS JSON structure.

  • affiliate_id : Your Affiliate ID
  • attribution : string ‘honor’ or ‘memory’ attributes the donation ‘in honor of’ or ‘in memory of’ respectively.
  • attribution_name : The full name of the individual being attributed the donation. This name appears in receipting and correspondence.
  • attribution_email : The email address to send notifications to, of attribution.  This may be the attributed individual, or their family etc.
  • _cb_success : On donation success, we can notify a 3rd party system of a completed transaction.  Detailed below.

Example:

var FG_DONATE_BUTTON_PARAMS ={
	affiliate_id:'acb-123',
	attribution:"memory",
	attribution_name:'Foo Bar',
	attribution_email:"foobars_family@domain.com",
}


_cb_success
 _cb_success is expected to be a base64 encoded URL which is unpacked and called via the GET method upon the successful processing of a donation.  The callback subsystem appends several new variables to the supplied URL which can be ingested by the 3rd party system.  These variables include :

  • _fg_popup_transaction_id : The unique transaction Id of the donation
  • _fg_popup_date : UTC time of processing completion
  • _fg_popup_organization_name : Name of the Non Profit receiving the donation
  • _fg_popup_organization_id : The unique ID of the organization receiving the donation.  This ID can also be used to retrieve further info about the Non Profit via the Charity Search API.
  • _fg_popup_attribution : The complete attribution string, eg:  ‘In Memory Of Foo Bar’
  •  _fg_popup_amount : USD donation amount.
  • _fg_popup_donor_name : The name of the Donor making the donation
  • _fgp_email : The email of the Donor making the donation
  • _fgp_address : The address of the Donor making the donation
  • _fgp_city : The city of the Donor making the donation
  • _fgp_state : The state of the Donor making the donation
  • _fgp_zip : The zip of the Donor making the donation
  • _fgp_country : The country of the Donor making the donation

The callback also generates a signature for the request which can be verified against the Donate Button to ensure the received message originated from the Donate Button and not an arbitrary 3rd party.  This signature exists in the request header ‘Fg-Popup-Signature‘ and can be confirmed by calling the URLhttp://donate.firstgiving.com/cbverify/{Fg-Popup-Signature}?payload={Base64 encoded GET request received, including FQDN} The signature verification service will return either a 200 OK on success, or a 404 on verification failure. Example here.

FirstGiving Donation API

The FirstGiving Donations API allows 3rd party developers to securely submit donations to nonprofits. Donations made with our API will automatically be disbursed to non-profit organizations each month. Our REST-style API means you can utilize this service from any programming language.

API Methodology

The Donations API exposes a simple HTTPS REST-style API with XML responses. As a developer, you must first register your application to receive a developer key and secret.

Development Sandbox

The Donations API Sandbox is a self-contained environment within which you can prototype and test FirstGiving API features. The sandbox is an almost identical copy of the live Donations API. Its purpose is to give developers a shielded environment for testing and integration purposes and to help avoid problems that might occur while testing FirstGiving integration solutions on the live site. Before moving any FirstGiving-based application into production, you should test the application in the Sandbox to ensure that it functions as you intend and within the guidelines and standards set forth by FirstGiving. Do not submit real credit card donations to our sandbox environment because this environment does not have the same security measures in place as our production environments. Only submit test data to the sandbox.

Production Donations API Server
https://api.firstgiving.com/

Sandbox Donations API Server
http://usapisandbox.fgdev.net/

Test Card Data for Sandbox

  • ccNumber – 4457000100000009
  • ccType – VI
  • ccExpDateMonth – 01
  • ccExpDateYear – 18
  • billToAddressLine1 – 1 Main St.
  • billToCity – Burlington
  • billToState – MA
  • billToZip – 01803

You may use random test data for other required fields.

Quick Start

The format for accessing our API uses this format: https://(server)/(resource)/(parameters) As a proper example, if your app were submitting a donation to our API, the absolute URL you connect to would look something like this: https://api.firstgiving.com/donation/creditcard

Specifying A Method
We use HTTP methods in order to determine what you want to do with a resource. Note that not all methods are supported on all resources. ”’GET”’ – Fetch resource(s) from FirstGiving. ”’POST”’ – Create a new resource. ”’PUT”’ – Modify a resource. ”’DELETE”’ – Remove a resource.

HTTP Status Codes
The following HTTP status codes will be returned from API requests: ”’200”’ GET/PUT/DELETE request succeeded ”’201”’ POST request succeeded (resource created) ”’400”’ Parameter missing. ”’403”’ Forbidden. ”’404”’ Unknown API Call. ”’405”’ Method not allowed. ”’500”’ Internal Error – contact FirstGiving.com.

Providing Input Values
Parameters must be passed as URL encoded values and sent via the standard HTTP mechanism depending on which method is invoked. For example, the HTTP GET method specifies that name/value pairs are sent via a query string appended to the URL.

Responses
The HTTP response body will contain a packet of XML containing elements and attributes that describe the results of your REST call. In the XML, the root “document element” is named “firstGivingDonationApi”. Any response from our API endpoint will be enclosed inside of a pair of tags.

The first child element you will find inside of the document element is an element titled “firstGivingResponse”. This tag is the container for the main payload of data that is returned. To help illustrate, the following is a response that came back after we tested the creditcarddonation resource’s PUT method with valid data…

a-0a107d601da34a45b29680

API Authentication
In order to submit requests against our API, you must first signup as a FirstGiving.com API partner. We will give you what we call an “application id” and a “security token”. This is similar to a username & password. You will identify your requests with your application token and security id on each request.

How To Provide Authentication Details
You must pass your application id and token in the HTTP request header. The name of the parameters are “JG_APPLICATIONKEY”, and “JG_SECURITYTOKEN”. An example request header might look like this: JG_APPLICATIONKEY: samplekey JG_SECURITYTOKEN: samplepassword

Resources

/donation/creditcard
Represents a credit card donation. Methods supported: “POST”.
POST Input Values

  • ccNumber – Required. User’s credit card number.
  • ccType – User’s credit card type. * “VI” ‐ Visa * “MC” ‐ MasterCard * “DI” ‐ Discover Card * “AX” – American Express
  • ccExpDateYear – Required. The 4 digit year the card expires.
  • ccExpDateMonth – Required. The 2 digit month the card expires.
  • ccCardValidationNum – Required. Card security number. Valid values include the following: * “CVV2″ ‐ Visa. (three‐digit value) * “CVC2″ ‐ MasterCard. (three‐digit value) * “CID” ‐ American Express. (four‐digit value)
  • billToTitle – The donor’s “title”, such as “Mr.”, “Mrs.”, “Dr.” etc. (Max length: 10)
  • billToFirstName – Required. The customer’s first name. (Max length 100).
  • billToMiddleName – The customer’s middle name. (Max length 100).
  • billToLastName – Required. The customer’s last name. (Max length 100).
  • billToAddressLine1 – Required. Address line 1 for customer bill to address. (Max length: 255)
  • billToAddressLine2 – Address line 2 for customer bill to address. (Max length: 255)
  • billToAddressLine3 – Address line 3 for customer bill to address. (Max length: 255)
  • billToCity – Required. City value for customer bill to address. (Max length: 35)
  • billToState – Required when billToCountry is US. State name for customer bill to address. In the US, the two character state code should be used. E.g., “FL”, “NY”, etc instead of “Florida” or “New York”. The full list of valid US state codes can be found here (Max length 30)
  • billToZip – Required. Zip for customer bill to address. (Max length 20)
  • billToCountry – Required. Two character Country code for customer bill to address. The country names corresponding to the abbreviations can be found in the ISO 3166-1 standard. Example: “US”. The full list of countries accepted by the donations API can be found here. (Max length: 3)
  • billToEmail – Required. Email address that corresponds to the customer bill to address. (Max length: 100)
  • billToPhone – Phone number that corresponds to the customer bill to address. (Max length: 20)
  • remoteAddr – Required. The end user’s IP address. This optional parameter is used to block common sources of fraud.
  • amount – Required. The amount of currency units to be donated. This should be in decimal format. Example: “1.23″ (without quotes). The minimum value is “1.00″.
  • currencyCode – The currency code for the currency that describes the number of units to withdraw from the donor’s account. * “USD”
  • charityId – Required. A UUID identifier provided by FirstGiving which identifies the recipient of the donation.
  • eventId – An identifier provided by FirstGiving which identifies the event associated with the donation. If donation does not relate to an event id, pass “” (zero length string).
  • fundraiserId – A universally unique ID which identifies the user account that was responsible for the donation that was collected. This is almost always a different person than the donor.
  • orderId – A universally unique ID genereated by the 3rd party which identifies the donation in their system.
  • description – Required. A short textual description of the donation.
  • reportDonationToTaxAuthority – Boolean (1|0) indicating whether or not this donation should be reported to the tax authority in the donor’s country. *Not applicable in the U.S.
  • personalIdentificationNumber – The national id number assigned to the donor who wants the donation reported to the tax authority. If the customer does not want the donation reported, just pass a blank string here.  *Not applicable in the U.S.
  • donationMessage – Message from donor to the charity.
  • honorMemoryName – Name of individual or organization that the donation was made to honor.
  • pledgeId – A user defined field that persists to the NPO report linking the transaction from your page to the FirstGiving System.
  • campaignName – A free-text field that persists to the NPO report notifying the NPO of the user defined Campaign Name.  If the Campaign Name ranks within the top 5 campaigns during the pay cycle, the Campaign Name will also appear on the NPO check stub.
  • commissionRate – (optional) The Retail Transaction Fee percentage to be withheld from the donation. This must be greater than the FirstGiving Fees (4.25%) and less than the Maximum Fee (FirstGiving Fees + Licensee Profit Percentage) configured at the time of setup. For example, passing “9.25” with a $100.00 transaction will have $9.50 taken as the Retail Transaction Fee, which will then be split into $4.25 to cover the FirstGiving Fees and leave $5.00 for your Licensee Profit Percentage/Partner Commission.

POST Response Values

  • transactionId – An ID number assigned by FirstGiving which uniquely identifies this donation transaction.

Example:

a-0a107d601da34a45b29680

/donation/recurringcreditcardprofile
Represents a recurring credit card donation. Methods supported: “POST”. Please read our full section on recurring donations to fully understand all of the details of this feature.

POST Input Values

  • ccNumber – User’s credit card number.
  • ccType – User’s credit card type. * “VI” ‐ Visa * “MC” ‐ MasterCard * “DI” ‐ Discover Card * “AX” ‐ American Express
  • ccExpDateYear – The 4 digit year the card expires.
  • ccExpDateMonth – The 2 digit month the card expires.
  • ccCardValidationNum – Card security number. Valid values include the following: * “CVV2″ ‐ Visa. (three‐digit value) * “CVC2″ ‐ MasterCard. (three‐digit value) * “CID” ‐ American Express. (four‐digit value)
  • billToTitle – The donor’s “title”, such as “Mr.”, “Mrs.”, “Dr.” etc. (Max length: 10)
  • billToFirstName – The customer’s first name. (Max length 100).
  • billToMiddleName – The customer’s first name. (Max length 100).
  • billToLastName – The customer’s last name. (Max length 100).
  • billToAddressLine1 – Address line 1 for customer bill to address. (Max length: 255)
  • billToAddressLine2 – Address line 2 for customer bill to address. (Max length: 255)
  • billToAddressLine3 – Address line 3 for customer bill to address. (Max length: 255)
  • billToCity – City value for customer bill to address. (Max length: 35)
  • billToState – State name for customer bill to address. (Max length 30)
  • billToZip – Zip for customer bill to address. (Max length 20)
  • billToCountry – Country code for customer bill to address. The country names corresponding to the abbreviations can be found in the ISO 3166-1 standard. Example: “US”. (Max length: 3)
  • billToEmail – Email address that corresponds to the customer bill to address. (Max length: 100)
  • billToPhone – Phone number that corresponds to the customer bill to address. (Max length: 20)
  • remoteAddr – The end user’s IP address. This optional parameter is used to block common sources of fraud.
  • amount – The amount of currency units to be donated. This should be in decimal format. Example: “1.23″ (without quotes).
  • currencyCode – The currency code for the currency that describes the number of units to withdraw from the donor’s account. * “USD”
  • charityId – A required numeric identifier provided by FirstGiving which identifies the recipient of the donation.
  • eventId – An identifier provided by FirstGiving which identifies the event associated with the donation. If donation does not relate to an event id, pass “” (zero length string).
  • fundraiserId – A universally unique ID which identifying the user account that was responsible for the donation that was collected. This is almost always a different person than the donor.
  • orderId – A universally unique ID genereated by the 3rd party which identifies the donation in their system.
  • description – A short textual description of the donation.
  • reportDonationToTaxAuthority – Boolean (1|0) indicating whether or not this donation should be reported to the tax authority in the donor’s country. *Not applicable in the U.S.
  • personalIdentificationNumber – The national id number assigned to the donor who wants the donation reported to the tax authority. If the customer does not want the donation reported, just pass a blank string here.  *Not applicable in the U.S.
  • donationMessage – Message from donor to the charity.
  • honorMemoryName – Name of individual or organization that the donation was made to honor.
  • billingDescriptor – A short phrase that describes the transaction. This phrase might be used on the donor’s credit card statement to help describe the donation based on FirstGiving’s processing internal rules.
  • recurringBillingFrequency – The type of recurring schedule that should be observed by the recurring donations engine. Acceptable values are: * MONTHLY * QUARTERLY * SEMIYEARLY * YEARLY
  • recurringBillingTerm – A number which indicates how many times the recurring donation should take place at the frequency described by “recurringBillingFrequency”. Use the value of “0″ to indicate there is no limit. For example, a frequency of “MONTHLY” with a term of 2 means that the customer will be billed on a monthly basis only 2 times.
  • pledgeId – A user defined field that persists to the NPO report linking the transaction from your page to the FirstGiving System.
  • campaignName – A free-text field that persists to the NPO report notifying the NPO of the user defined Campaign Name.  If the Campaign Name ranks within the top 5 campaigns during the pay cycle, the Campaign Name will also appear on the NPO check stub.
  • commissionRate – (optional) The total processing fee percentage to be withheld from the donation. For example, pass “7.5”  to have for $7.50 withheld from a $100 donation. This must be greater than the FirstGiving fee (4.25%) and less than the maximum fee configured at the time of setup. If not passed, the maximum value is used.

POST Response Values

  • recurringDonationProfileId – An ID number assigned by FirstGiving which uniquely identifies this donation transaction.

Example

4d2748d395c34

Test Card Data for Sandbox
Any of the following test card numbers should be used for submitting recurring transactions to the sandbox environment. Other card numbers may return invalid responses.

  • Visa 4111111111111111
  • Visa 4012888888881881
  • MasterCard 5105105105105100
  • MasterCard 5555555555554444
  • Discover 6011000990139424
  • Discover 6011111111111117
  • American Express Corporate 378734493671000
  • American Express 371449635398431
  • American Express 378282246310005

Card on File

The donations API also supports tokenizing credit cards for billing against at a later date. Documentation for this feature is located separately here.

/verify
Verify a message that you have received actually originated from FirstGiving’s API.
GET Input Values

  • message – The HTTP body of an API response from FirstGiving’s API, or, an HTTP query string that was sent as part of an HTTP request which originated from FirstGiving’s API.
  • signature – The “Jg-Response-Signature” HTTP header sent with a FirstGiving API response, or, the “Jg-Request-Signature” header sent with a request that originated from FirstGiving’s API.

GET Response Values

  • valid – Boolean value of 1 or 0 indicating whether or not the signature matches the message that you are providing.
  • signature – The signature value you provided.
  • message – The message value you provided.

GET Response Values

1
9fe66a3c40ce0296e5469679635dc345

 

Transaction Lookup

Information about previously submitted transactions can be retrieved by using the transaction lookup endpoints described in the documentation located here.

Refunds

Refunds can be requested via a REST endpoint, described here.

More Details

Recurring Donations
FirstGiving exposes an API method allowing 3rd parties to create recurring donation profiles. A recurring donation profile can be thought of as an automated donations schedule that the FirstGiving system will observe. Based on the schedule you create, the FirstGiving billing system will “trigger” meaning that FirstGiving will charge a donor’s card for the amount specified in the recurring donations profile. Upon creating a recurring donation profile with the FirstGiving API, FirstGiving creates a recurring donation profile ID. Please note that this does not represent a transaction. Rather, it is a profile ID which represents the donations schedule within the FirstGiving system. A recurring donation profile usually “triggers” for the first time approximately 48 hours after the profile was created. For example, a monthly recurring donation created on January 15th will likely trigger for the first time on January 17th, and every 30 days thereafter.

Email Receipt Delivery
FirstGiving will automatically send a donation receipt to the email associated with the donor. This email contains the updated contact information for the FirstGiving customer service team that the donor may use if they have questions about a donation, or a recurring billing profile. An example of the email template is here.

Instant Donation Notifications
Some 3rd parties may want to execute custom logic when a recurring donation is made. Our system implements an instant donation notification feature which will invoke a URL on your server when a recurring profile triggers. To utilize this feature, you must contact FirstGiving and provide our team with the URL that our engine should request when a recurring donation is detected. The notifications engine will automatically add two query string params to the GET request that we send to your page: transactionId and recurringDonationProfileId. For example, if your callback URL is http://www.example.com/recurringnotification.php then our system would formulate a request and query string like http://www.example.com/recurringnotification.php?transactionId=A&recurringDonationProfileId=B Our system will try to deliver that message to your endpoint multiple times for up to 4 days. We consider the message to be delivered if your page returns an HTTP status code of 200. Using this pattern, you could send a custom thank you email to a donor confirming that their donation has been made.

Verifying Messages Come From FirstGiving’s API
In the example above, you may wish to ensure that the donation notification request actually came from FirstGiving. For example, a malicious user with access to your callback URL could invoke that URL thereby causing your system to react as if a real donation was made. You need to be able to verify that the message actually comes from FirstGiving’s API. Use our “/verify” API resource to verify that a “message” that you think might have come from our system actually originated from FirstGiving. In the example above, the “message” we sent you is the HTTP query string value of “transactionId=A&recurringDonationProfileId=B”. In each message we send, we also send out a cryptographic “signature” value that helps you validate messages. The signature value may be found in the HTTP request header and is named “Jg-Request-Signature”. See the section above on how the /verify resource works.

Exceptions
When an exception occurs, you should receive a 400 or 500 HTTP response code and XML document from the API server. The XML document will confirm the exception with a few details:

  • acknowledgement – During error conditions, this will bet set to “Failed”
  • friendlyErrorMessage – A message you may wish to display to the end user. We recommend creating your own custom error messages rather than using ours.
  • verboseErrorMessage – The underlying exception details. This is useful for software engineers who are trying to debug the real problem. In some cases, the FirstGiving system will recognize an error condition and explain the error in terms you will understand. In other cases, an exception happens deeper within the banking subsystems and we then subsequently pass the underlying error message directly from the banking subsystem directly you.
  • errorTarget – During a simple data input validation error, we will include an extra attribute on the firstGivingResponse element called “errorTarget” which names the input param which caused the error. This is only available when the exception has to do with invalid input data. In general, you should do input validation in your app to reduce these types of errors. If, for example, you send an amount of “FOO”, our input validator would identify that as not being numeric and set the errorTarget to “amount” allowing you to possibly create a red error message next to the amount input field. Errors derived deeper in the system do not produce errorTarget values.

Example:

-
Card On File

You are able to store a donor’s credit card allowing for simplified donation actions later on. A few points about our card on file implementation:

  • FirstGiving does not actually store any card details. Instead, we use a secured payment gateway behind the scenes.
  • Our API servers do not retain any trace of the card details – not even in our web server logs.
  • Consumer card data is transmitted using SSL as it flows through our systems.

Card On File Integration Flow

  • 3rd party website uses /cardonfile REST resource to store a card. A cardOnFileId is returned.
  • Later, 3rd party website uses the cardOnFileId in order to create a donation (instead of all of the card details).

Storing A Card On File: HTTP POST to /cardonfile

Registers a donor’s card for storage under your API keypair. We return an ID number, or “token”, which can be used later to create a donation. Get Query String Input Params:

  • ccNumber – Required. User’s credit card number.
  • ccType – Required. User’s credit card type. * “VI” ‐ Visa * “MC” ‐ MasterCard * “DI” ‐ Discover Card * “AX” – American Express
  • ccExpDateMonth – Required. The 2 digit month the card expires.
  • ccExpDateYear – Required. The 4 digit year the card expires.
  • ccCardValidationNum – Required. Card security number. Valid values include the following:
  • * “CVV2″ ‐ Visa. (three‐digit value) * “CVC2″ ‐ MasterCard. (three‐digit value) * “CID” ‐ American Express. (four‐digit value)
  • accountName – Required. The name on the card. (Max length 60).
  • billToFirstName – Required. The customer’s first name. (Max length 60).
  • billToMiddleName – Optional. The customer’s middle name. (Max length 60).
  • billToLastName – Required. The customer’s last name. (Max length 60).
  • billToAddressLine1 – Required. Address line 1 for customer bill to address. (Max length: 60)
  • billToAddressLine2 – Optional. Address line 2 for customer bill to address. (Max length: 60)
  • billToAddressLine3 – Optional. Address line 3 for customer bill to address. (Max length: 60)
  • billToCity – Required. City value for customer bill to address. (Max length: 60)
  • billToState – Required. 2-character state code if within The United States. Foreign country should pass the province/region name. (Max length 60)
  • billToZip – Required. Zip for customer bill to address. (Max length 30)
  • billToCountry – Required. Country code for customer bill to address. The country names corresponding to the abbreviations can be found in the ISO 3166-1 standard. Example: “US”. (Max length: 2)
  • billToEmail – Required. Email address that corresponds to the customer bill to address. (Max length: 50)
  • billToPhone – Optional. Phone number that corresponds to the customer bill to address. (Max length: 30)
  • remoteAddr – Required. The end user’s IP address. Used to block common sources of fraud. (Max length: 15)

Note: billToEmail must not contain the special character ‘+’. While it is possible to create a card on file token with email addresses formatted in this way, subsequent attempts to charge those tokens will fail.

Get Response Example: <?xml version=”1.0″ encoding=”UTF-8″?> <firstGivingDonationApi> <firstGivingResponse acknowledgement=”Success”> <cardOnFileId>3c5e29a0-b96e-11e0-a4dd-0800200c9a66</cardOnFileId> </firstGivingResponse> </firstGivingDonationApi>

Storing a Card On File: Hosted Payment Page

You can also use our hosted payment page to exchange card information for a token while limiting PCI scope. Simply embed the iframe in your application and we’ll post back a token, which you can use in lieu of the card details to charge the donor at a later day.

To access the page, use an iFrame with the URL in the following format: {PAGE_ENVIRONMENT_URL}/secure/tokenrequest?{URL_PARAMETERS}

Usage
This will post back a token, which you can then process a donation against via the API method here.

Example
Here’s an example of a functional staging URL: https://donatenowstaging.firstgiving.com/secure/tokenrequest?country=US&first_name=Steve&last_name=Smith&affiliate_id=b8a11313-b42a-4fa4-8e89-a41adf100cf3&_pb_success=aHR0cDovL3d3dy5maXJzdGdpdmluZy5jb20

Required URL Parameters

  • affiliate_id – a token which uniquely identifies the 3rd party partner ( that’s you)  that this payment page belongs to (in the sandbox/staging environment, please use affiliate_id=b8a11313-b42a-4fa4-8e89-a41adf100cf3).
  • _pb_success– this is the URL of the page to be redirected to after a donation is successfully submitted. This MUST be a base64 encoded value. In the above example it is the base64 encoded URL ‘http://www.firstgiving.com/’.

Optional URL Parameters
There are also these additional optional URL parameters which when provided will prepopulate those corresponding form fields:

  • email
  • first_name
  • last_name
  • address_line_1
  • city
  • country
  • postal_code
  • region – (this is the state field for US addresses)

Additional parameters which allow you to control the look and feel of the iFrame:

  • buttonText
  • styleSheetURL – This is passed to the iframe as a 64bit encoded url, as in “styleSheetURL=aHR0cDovL3l1aS55YWhvb2FwaXMuY29tLzMuMTAuMi9idWlsZC9jc
    3NyZXNldC9jc3NyZXNldC1taW4uY3Nz.” You’ll want to use this base stylesheet as a template to preserve the structure of the page: http://donate.firstgiving.com/dpa/static/css/payment.css.

Sandbox AVS

When performing integration testing with the Sandbox Donations API environment, the specific CVV of 150 should be used along with the normal test card data as detailed in the primary Donations API documentation in order to guarantee a successful response. Submitting other CVV values may result in an AVS failure response message.

Processing New Donation with Card On File: HTTP POST to /donation/creditcard

In order to trigger a charge against a card which is stored on file, you use the normal /donation/creditcard resource documented on the main Donations API page. However, the difference is that you should omit all of the following fields:

  • ccNumber
  • ccType
  • ccExpDateYear
  • ccExpDateMonth
  • ccCardValidationNum
  • billToTitle
  • billToFirstName
  • billToMiddleName
  • billToLastName
  • billToAddressLine1
  • billToAddressLine2
  • billToAddressLine3
  • billToCity
  • billToState
  • billToZip
  • billToCountry
  • billToEmail
  • billToPhone
and include:
  • cardOnFileId – The card on file ID number you would like to execute the donation with.
Country Code

The Donations API supports the following list of valid two character country code values:

  • US: United States
  • CA: Canada
  • AF: Afghanistan
  • AL: Albania
  • DZ: Algeria
  • AS: American Samoa
  • AD: Andorra
  • AO: Angola
  • AI: Anguilla
  • AQ: Antarctica
  • AG: Antigua and Barbuda
  • AR: Argentina
  • AM: Armenia
  • AU: Australia
  • AT: Austria
  • AZ: Azerbaidjan
  • BS: Bahamas
  • BH: Bahrain
  • BD: Bangladesh
  • BB: Barbados
  • BY: Belarus
  • BE: Belgium
  • BZ: Belize
  • BJ: Benin
  • BM: Bermuda
  • BT: Bhutan
  • BO: Bolivia
  • BA: Bosnia-Herzegovina
  • BW: Botswana
  • BR: Brazil
  • BN: Brunei Darussalam
  • BG: Bulgaria
  • BF: Burkina Faso
  • BI: Burundi
  • KH: Cambodia
  • CM: Cameroon
  • CV: Cape Verde
  • KY: Cayman Islands
  • CF: Central African Republic
  • TD: Chad
  • CL: Chile
  • CN: China
  • CO: Colombia
  • KM: Comoros
  • CG: Congo
  • CR: Costa Rica
  • HR: Croatia
  • CU: Cuba
  • CY: Cyprus
  • CZ: Czech Republic
  • DK: Denmark
  • DJ: Djibouti
  • DM: Dominica
  • DO: Dominican Republic
  • EC: Ecuador
  • EG: Egypt
  • SV: El Salvador
  • GQ: Equatorial Guinea
  • ER: Eritrea
  • EE: Estonia
  • ET: Ethiopia
  • FK: Falkl and Islands
  • FJ: Fiji
  • FI: Finland
  • FR: France
  • GF: French Guyana
  • GA: Gabon
  • GM: Gambia
  • GE: Georgia
  • DE: Germany
  • GH: Ghana
  • GI: Gibraltar
  • GB: Great Britain
  • GR: Greece
  • GD: Grenada
  • GP: Guadeloupe (French)
  • GT: Guatemala
  • GN: Guinea
  • GW: Guinea Bissau
  • GY: Guyana
  • HT: Haiti
  • HN: Honduras
  • HK: HongKong
  • HU: Hungary
  • IS: Iceland
  • IN: India
  • ID: Indonesia
  • IR: Iran
  • IQ: Iraq
  • IE: Ireland
  • IL: Israel
  • IT: Italy
  • CI: Ivory Coast (CoteD’Ivoire)
  • JM: Jamaica
  • JP: Japan
  • JO: Jordan
  • KZ: Kazakhstan
  • KE: Kenya
  • KI: Kiribati
  • KW: Kuwait
  • KG: Kyrgyzstan
  • LA: Laos
  • LV: Latvia
  • LB: Lebanon
  • LS: Lesotho
  • LR: Liberia
  • LY: Libya
  • LT: Lithuania
  • LU: Luxembourg
  • MO: Macau
  • MK: Macedonia
  • MG: Madagascar
  • MW: Malawi
  • MY: Malaysia
  • MV: Maldives
  • ML: Mali
  • MT: Malta
  • MH: Marshall Islands
  • MQ: Martinique (French)
  • MR: Mauritania
  • MU: Mauritius
  • YT: Mayotte
  • MX: Mexico
  • FM: Micronesia
  • MD: Moldavia
  • MN: Mongolia
  • MS: Montserrat
  • MA: Morocco
  • MZ: Mozambique
  • MM: Myanmar
  • NA: Namibia
  • NR: Nauru
  • NP: Nepal
  • NL: Netherlands
  • AN: Netherlands Antilles
  • NC: New Caledonia (French)
  • NZ: New Zealand
  • NI: Nicaragua
  • NE: Niger
  • NG: Nigeria
  • KP: North Korea
  • NO: Norway
  • OM: Oman
  • PK: Pakistan
  • PW: Palau
  • PA: Panama
  • PG: Papua New Guinea
  • PY: Paraguay
  • PE: Peru
  • PH: Philippines
  • PN: Pitcairn Island
  • PL: Poland
  • PF: Polynesia (French)
  • PT: Portugal
  • QA: Qatar
  • RE: Reunion (French)
  • RO: Romania
  • RU: Russian Federation
  • RW: Rwanda
  • GS: S. Georgia & S. Sandwich Isls.
  • SH: Saint Helena
  • KN: Saint Kitts & Nevis Anguilla
  • LC: Saint Lucia
  • PM: Saint Pierre and Miquelon
  • ST: Saint Tome (SaoTome) and Principe
  • VC: Saint Vincent & Grenadines
  • WS: Samoa
  • SA: Saudi Arabia
  • SN: Senegal
  • SC: Seychelles
  • SL: Sierra Leone
  • SG: Singapore
  • SK: Slovak Republic
  • SI: Slovenia
  • SB: Solomon Islands
  • SO: Somalia
  • ZA: South Africa
  • KR: South Korea
  • ES: Spain
  • LK: SriLanka
  • SD: Sudan
  • SR: Suriname
  • SZ: Swaziland
  • SE: Sweden
  • CH: Switzerland
  • SY: Syria
  • TJ: Tadjikistan
  • TW: Taiwan
  • TZ: Tanzania
  • TH: Thailand
  • TG: Togo
  • TO: Tonga
  • TT: Trinidad and Tobago
  • TN: Tunisia
  • TR: Turkey
  • TC: Turks and Caicos Islands
  • TV: Tuvalu
  • UG: Uganda
  • UA: Ukraine
  • AE: United Arab Emirates
  • GB: UnitedKingdom
  • UY: Uruguay
  • UZ: Uzbekistan
  • VU: Vanuatu
  • VE: Venezuela
  • VN: Vietnam
  • VG: Virgin Islands (British)
  • WF: Wallis and Futuna Islands
  • EH: Western Sahara
  • YE: Yemen
  • ZM: Zambia
  • ZW: Zimbabwe
Email Templates

Donation Notification Template

Dear __DONOR_NAME__,

Thank you very much for your generous $__AMOUNT__ donation to __ORG_NAME__.

Your donation on __APPLICATIONNAME__ was processed today by FirstGiving.com.

The donation you have made is tax-deductible to the extent allowed by law.You may save or print this receipt for your records.This email certifies that you have made this donation as a charitable contribution.This receipt may be useful to you when completing your tax return.

Website/App:
 __APPLICATIONNAME__

 Date:
 __DATE_NOW__

 Nonprofit Name:
 __ORG_NAME__

 Amount:
 $__AMOUNT__

 Donor Name:
 __DONOR_NAME__

 Donation Reference(Transaction ID)#:
 __TX_ID__

 This donation should appear on your bank statement as'__DESCRIPTOR__'

 __EXTRA__

Thank you for your donation!

---
This message was sent to __REC_EMAIL__ because a charitable donation was processed via the FirstGiving.com donations gateway for __ORG_NAME__ associated with your email address.

For questions or customer service about your donation, you may reply to this email, visit http://www.firstgiving.com/content/contact-us, or call customer service at (617) 542-0010 between the hours of 9AM-5PM EST Monday-Friday.

FirstGivingis located at 34FarnsworthStreet,3rdFloor,Boston, MA 02110, USA.

 

Donation Receipt Template

Dear __DONOR_NAME__,

Thank you very much for your generous $__AMOUNT__ donation to __ORG_NAME__.

Your donation on __APPLICATIONNAME__ was processed today by a company called FirstGiving.com.You may not have heard of us, but we help websites process secure donations.If you have any questions or customer service needs related to today's donation, please contact FirstGiving via the contact information below.

Your donation may be tax-deductible; please contact __ORG_NAME__ for more information. 

Website/App:
__APPLICATIONNAME__

Date:
__DATE_NOW__

Nonprofit Name:
__ORG_NAME__

Amount:
$__AMOUNT__

Donor Name:
__DONOR_NAME__

Donation Reference (Transaction ID) #:
__TX_ID__

This donation should appear on your bank statement as '__DESCRIPTOR__'

__EXTRA__
What Is FirstGiving.com?

FirstGiving.com helps non-profits and charity websites raise money and process donations. For more information about our company, visit

http://www.firstgiving.com/

Thank you for your generous donation!

---
This message was sent to __REC_EMAIL__ because a charitable donation was processed via the FirstGiving.com donations gateway for __ORG_NAME__ associated with your email address.

For questions or customer service about your donation, you may reply to this email, visit http://www.firstgiving.com/content/contact-us, or call customer service at (617) 542-0010 between the hours of 9AM-5PM EST Monday-Friday.

FirstGiving is located at 34 Farnsworth Street, 3rd Floor,  Boston, MA 02110, USA.

 

Recurring Donation Confirmation Template

Dear __DONOR_NAME__,

Note:This is not a receipt!Instead,this is a confirmation that you have created a recurring donation which should begin within 48 hours.

The donation you made on __APPLICATIONNAME__ was processed today by a company called FirstGiving.com.You may not have heard of us, but we help websites process secure donations.If you have any questions or customer service needs related this message, please contact FirstGiving via the contact information below.

Thank you very much for your generous __INTERVAL__ recurring donation of $__AMOUNT__ to __ORG_NAME__. Contributions made with this recurring donation will be tax-deductible to the extent allowed by law.This email certifies that you have setup this recurring donation as a charitable contribution.*Please note that your first recurring donation will take place in approximately 48 hours and that you have not yet made any donations.

Website/App:
__APPLICATIONNAME__

Setup Date:
__DATE_NOW__

Donor Name:
__DONOR_NAME__

Nonprofit Name:
__ORG_NAME__

Amount:
$__AMOUNT__ / __INTERVAL__

How Many Times Your Donation Be Made With This Schedule:
__TERM__

Donation Reference (Recurring Donation Profile ID)#:
__TX_ID__

Donations should appear on your bank statement as'__DESCRIPTOR__'.

Thank you for your donation,The FirstGiving.com Team

---

This message was sent to __REC_EMAIL__ because a recurring donations profile was made for __ORG_NAME__ that is managed byFirstGiving.com.You can learn more about FirstGiving by navigating to http://firstgiving.com/content/about-us/overview

For questions or customer service about your recurring donation profile, you may reply to this email, visit http://www.firstgiving.com/content/contact-us, or call customer service at (617) 542-0010 between the hours of 9AM-5PM EST Monday-Friday.

FirstGivingis located at 34FarnsworthStreet,3rdFloor,Boston, MA 02110, USA.
Refunding Transactions

The donations API provides a method to allow a partner to request a refund for a transaction.

API Authentication

The following API methods all require standard API authentication headers as described in the main donations API documentation. You must pass your application id and token in the HTTP request header. The name of the parameters are “JG_APPLICATIONKEY”, and “JG_SECURITYTOKEN”. An example request header might look like this: JG_APPLICATIONKEY: samplekey JG_SECURITYTOKEN: samplepassword

/transaction/refundrequest

A transaction Id  or donation Id is provided as an input parameter. Only transactions which were originally submitted by the authenticated API key can be looked up. A transaction Id which does not exist or that was not created by the requesting user will result in identical 404 failure responses.

GET Input Values

  • transactionId – The id of the transaction returned by the original donation POST. This will start with a letter and and dash.
  • donationId – The id of the transactions created by the FirstGiving system, available in reporting. This will be an integer.
  • tranType – the will be REFUNDREQUEST

Sample Request
curl -X GET -H “JG_APPLICATIONKEY: 434a712a-31ec-4c00-a3bf-782897af27e5″ -H “JG_SECURITYTOKEN: 35afbf1-07e4-4886-88f7-3ce34680eb6f” https://api.firstgiving.com/transaction/refundrequest?donationId=504614&tranType=REFUNDREQUEST

State Codes

When the selected Country is set to the value “US” then only the following two letter state codes will be accepted:

  • AL : Alabama
  • AK : Alaska
  • AZ : Arizona
  • AR : Arkansas
  • CA : California
  • CO : Colorado
  • CT : Connecticut
  • DC : District of Columbia
  • DE : Delaware
  • FL : Florida
  • GA : Georgia
  • HI : Hawaii
  • ID : Idaho
  • IL : Illinois
  • IN : Indiana
  • IA : Iowa
  • KS : Kansas
  • KY : Kentucky
  • LA : Louisiana
  • ME : Maine
  • MD : Maryland
  • MA : Massachusetts
  • MI : Michigan
  • MN : Minnesota
  • MS : Mississippi
  • MO : Missouri
  • MT : Montana
  • NE : Nebraska
  • NV : Nevada
  • NH : New Hampshire
  • NJ : New Jersey
  • NM : New Mexico
  • NY : New York
  • NC : North Carolina
  • ND : North Dakota
  • OH : Ohio
  • OK : Oklahoma
  • OR : Oregon
  • PA : Pennsylvania
  • RI : Rhode Island
  • SC : South Carolina
  • SD : South Dakota
  • TN : Tennessee
  • TX : Texas
  • UT : Utah
  • VT : Vermont
  • VA : Virginia
  • WA : Washington
  • WV : West Virginia
  • WI : Wisconsin
  • WY : Wyoming
  • GU : Guam
  • VI : Virgin Islands
  • PR : Puerto Rico
  • AS : American Samoa
Transaction Lookup

The donations API provides several methods to retrieve information about previously submitted transactions.

API Authentication

The following API methods all require standard API authentication headers as described in the main donations API documentation.

/transaction/detail

Request information about a specific transaction. A transaction Id is provided as an input parameter and the result is the information about the associated transaction. Only transactions which were originally submitted by the authenticated API key can be looked up. A transaction Id which does not exist or that was not created by the requesting user will result in identical 404 failure responses.

GET Input Values

  • transactionId – The id of the transaction returned by the original donation POST.

GET Response Values

The possible response fields closely mirror those input from the /donation/creditcard method. Not all possible fields may be returned. E.g., fields which weren’t provided in the original donation request or sensitive credit card information (the FirstGiving donations API never stores client card data). Responses also include fields with information about disbursement (status, paymentStatus, postingDate) and the breakdown of fees for the transaction (commissionFees, ccFees, totalFees, netToOrganization). If the transaction has not been completely processed, these fields may contain a simple string value of ‘FG_UNAVAILABLE’.

<?xml version="1.0" encoding="UTF-8"?>
<firstGivingDonationApi>
  <firstGivingResponseacknowledgement="Success">
   <transaction><transactionId>a-4f147b7eb0d67789831929</transactionId>
   <currencyCode>USD</currencyCode>
   <amount>5.0000</amount>
   <billToFirstName>Tiago</billToFirstName>
   <billToMiddleName/>
   <billToLastName>test</billToLastName>
   <billToAddressLine1>1 Main St.</billToAddressLine1>
   <billToAddressLine2/>
   <billToAddressLine3/>
   <billToCity>Burlington</billToCity>
   <billToState>MA</billToState>
   <billToZip>01803</billToZip>
   <billToCountry>US</billToCountry>
   <billToPhone/>
   <billToEmail> wiggum@sgf.com</billToEmail>
   <donationMessage/>
   <honorMemoryName/>
   <status>FG_UNAVAILABLE</status>
   <commissionFees>FG_UNAVAILABLE</commissionFees>
   <ccFees>FG_UNAVAILABLE</ccFees>
   <totalFees>FG_UNAVAILABLE</totalFees>
   <netToOrganization>FG_UNAVAILABLE</netToOrganization>
   <paymentId>FG_UNAVAILABLE</paymentId>
   <paymentStatus>FG_UNAVAILABLE</paymentStatus>
   <postingDate>FG_UNAVAILABLE</postingDate>
  </transaction>
 </firstGivingResponse>
</firstGivingDonationApi>

/transaction/list

It is also possible to get a list of all transaction Id’s.

<?xml version="1.0" encoding="UTF-8"?>
<firstGivingDonationApi>
 <firstGivingResponseacknowledgement="Success">
   <transactions>
   <transactionId>a-4f10b28c8320c799330405</transactionId>
   <transactionId>a-4f147b7eb0d67789831929</transactionId>
   <transactionId>a-4f147bdcc9c65546247134</transactionId>
  </transactions>
</firstGivingResponse>
</firstGivingDonationApi>

A maximum of 100 transaction Id’s at a time will ever be returned by this method. If the application has more transactions than this, there is a pagination feature which can be used to return the other transaction Id’s.

Get Input Values

  • page – specify the page number to return. The first page number is 1.
  • page_size – the maximum number of records to be included in each response (must be smaller than 100)
  • date_from – return only transactions created on or after this date. The format of the parameter is a unix timestemp.
  • count – this parameter with a value of ‘on’ will return the total number of transaction Id’s rather than the Id’s themselves.

Example /transaction/list with ‘count=on’:


 

<?xml version="1.0" encoding="UTF-8"?>
<firstGivingDonationApi>
  <firstGivingResponseacknowledgement="Success">
   <row_count>341</row_count>
  </firstGivingResponse> 
</firstGivingDonationApi>
Hosted Payment Page

If you want control over the experience of your entire checkout flow, without a full API integration, you can use our Hosted Payment Page. This involves embedding a ‘piece of a payment page’ (iFrame) which contains the card data capture fields. Since the iFrame is hosted by FirstGiving, you can avoid PCI headaches while maintaining a fully customizable payment page within your own website.

Usage

To access the page, use an URL in the following format:

{PAGE_ENVIRONMENT_URL}/secure/payment/{CHARITY_UUID}?{URL_PARAMETERS}

There are two different environment URLs that can be used:

  • Staging: https://donatenowstaging.firstgiving.com
  • Production: https://donate.firstgiving.com

Example URL

Here is an example of a functional staging URL:

https://donatenowstaging.firstgiving.com/secure/payment/03d1c5e4-2024-11e0-a279-4061860da51d?amount=15&amp;country=US&amp;first_name=Bob&amp;last_name=Dole&amp;affiliate_id=EXAMPLE_PARTNER&amp;_pb_success=aHR0cDovL3d3dy5maXJzdGdpdmluZy5jb20=&amp;campaignName=CampaignName1&amp;pledgeId=PledgeID2&amp;email=sample@frontstreampayments.com&amp;buttonText=PAY%20NOW

Parameters

Charity UUID
The charity UUID to donate to is the last portion of the URL before the query parameters. An example charity UUID looks like this: e9262f62-e209-11df-8a5c-12313b100879. Refer to the Charity Search API documentation for information on how to find the UUID’s for the charities you wish to support. The Nonprofit Search plugin can also optionally be integrated to provide a UI for end users to select the destination charity themselves.

Required URL Parameters
There are three required URL parameters:

  • amount – the donation dollar amount
  • affiliate_id – a token which uniquely identifies the 3rd party partner that this payment page belongs to.
  • _pb_success – this is the URL of the page to be redirected to after a donation is successfully submitted. This MUST be a base64 encoded value. In the above example it is the base64 encoded URL ‘http://www.firstgiving.com/’.

Optional URL Parameters
There are also these additional optional URL parameters which when provided will prepopulate those corresponding form fields:

  • email
  • first_name
  • last_name
  • address_line_1
  • city
  • country
  • postal_code
  • region – (Note: this is the state field)
  • commissionRate – The Retail Transaction Fee percentage to be withheld from the donation. This must be greater than the FirstGiving Fees (4.25%) and less than the Maximum Fee (FirstGiving Fees + Licensee Profit Percentage) configured at the time of setup. For example, passing “9.25” with a $100.00 transaction will have $9.50 taken as the Retail Transaction Fee, which will then be split into $4.25 to cover the FirstGiving Fees and leave $5.00 for your Licensee Profit Percentage/Partner Commission.

And additional parameters which allow you to control the look and feel of the iFrame

  • buttonText
  • styleSheetURLThis is passed to the iframe as a 64bit encoded url, as in “styleSheetURL=aHR0cDovL3l1aS55YWhvb2FwaXMuY29tLzMuMTAuMi9idWlsZC9jc3
    NyZXNldC9jc3NyZXNldC1taW4uY3Nz.” You’ll want to use this base stylesheet as a template to preserve the structure of the page: http://donate.firstgiving.com/dpa/static/css/payment.css.

Optional callback URL (See next section):

  • _cb_success
  • _cb_error

You’ll want to use a height of 710px and a width of 660px to accommodate the error labels. This is based on the standard styles, and might change if you’re using custom CSS.

Callbacks

_cb_success and _cb_error are server-side callbacks.  The FG app server calls these urls and the client is never exposed to them.  Their purpose is only to notify the affiliate’s server that a donation succeeded or failed. _pb_success is a client side redirect.  The browser is sent to this location after the donation has been successfully processed.  This feature only exists for the CC collection page where there is no other thank you page like for the Donate Button. I would use this for any app functionality. The ‘postback’ is called first then the ‘callback’ is called in the code if the URL parameters are set/passed in the iframe URL After a successful donation has been completed, the page redirects to the URL specified by the _pb_success parameter. When this URL is invoked it will include additional parameters about the donation appended to the end of it. These parameters are described in the Donation Button Callbacks documentation. Since the _pb_success URL is invoked by the client, it is not possible to verify that those requests have been legitimately called by the FirstGiving application. The extra information passed through that URL should not be trusted as authoritative information about donations that have been processed by the page. Instead, the _cb_success parameter should be used to provide an additional callback URL. It should be encoded in the same way as the _pb_success parameter. This URL will be called directly from the FirstGiving servers after a successful donation with the additional parameters passed to it. To verify the callback authenticity the callback also generates a signature for the request which can be verified to ensure the received message originated from FG.  This signature exists in the request header ‘Fg-Popup-Signature‘ and can be confirmed by calling the URL http://donate.firstgiving.com/cbverify/{Fg-Popup-Signature}?payload={Base64 encoded GET request received, including FQDN} The signature verification service will return either a 200 OK on success, or a 404 on verification failure. When the donation API responds with an error processing the transaction, if a _cb_error parameter has been provided, then the content of the error response will be POSTed to that URL. The content of the POST body will contain two fields: ‘target’ indicating the error target and ‘message’ with the verbose error message.

Nonprofit Search Plugin

The Nonprofit Search Plugin is a consumer facing widget for the Charity Search API. Here’s a live example:

Installation

It can be installed into any page via :

<divid="fgGraphWidgetContainer"></div><scriptsrc="http://assets.firstgiving.com/graphwidget/static/js/fg_graph_widget.min.js"></script>

The Widget uses jQuery (”noConflict”) and will include the library dynamically if the jQuery object does not already exist in the page.

Options

Several runtime options are supported via the FG_GRAPHWIDGET_PARAMS (JSON) structure. This should be instantiated prior to including the widget. It is important to note that this variable must be defined within the global scope in order to be detected by the widget.
nocss : if this parameter exists, the widget will not try to include remote CSS. Use this to define your own style sheet.
results.selectaction : Callback when a result has been selected (args uuid, charity_name, ein).

When a result has been selected, the charity uuid will automatically be populated to #fg_selected_charity_uuid

<divid="fgGraphWidgetContainer"></div><script>var FG_GRAPHWIDGET_PARAMS ={
results :{
selectaction :function(uuid, charity_name, ein){
alert('SELECTED '+ charity_name +' '+ uuid +' ein ('+ ein +')');}}};</script><scriptsrc="http://assets.firstgiving.com/graphwidget/static/js/fg_graph_widget.min.js"></script>
Webhooks

Webhooks allow you to collect information about events as they happen in near real-time. Provide a URL, and we’ll send you the details as the events take place. Configuring your server to receive a new webhook is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL. Webhooks are managed in your account dashboard. Login and navigate to ‘Webhooks’ in the left column.

Securing Webhooks

We currently support either HTTP or HTTPS urls, so you can use an SSL-enabled url. We recommend this if possible. But keep in mind that your endpoint is going to be wide-open on the internet, and you might not want others to be able to submit random data to your systems. We advise you to guard against replay-attacks by recording which events you receive, and never processing events twice. We also recommend that you check the isTest attribute of the webhook before processing events in your production environment. Webhook data is sent as JSON in the request’s body. The full event details are included and can be used directly. If security is a concern, or if it’s important to confirm that FirstGiving sent the webhook, you should only use the ID sent in your webhook, and subsequently request the details of the event via the Verify endpoint below.

Verify
You can verify the entire data payload of a notification given its signature.

Supported Events

  • Donation – This will fire every time you process a successful transaction
  • Refund – This will fire every time a transaction is reversed
  • Disbursement – This will fire when FirstGiving issues a payment to the benefiting nonprofit

Sample Payload

All events share a common payload structure. The request will be a post, and the data will be JSON in the request’s body. Here’s a sample:

<code>{
   "IsTest":true,
   "Signature":"bc605bec-e4c7-48a6-b3d8-15ec20a416a2",
   "ProcessStatus":"Refunded",
   "TransactionDate":"1\/20\/2014",
   "TransactionReference":"1234",
   "DonationId":456,
   "NonProfit":"Test Charity",
   "DonationAmount":100,
   "ProcessingFees":4.25,
   "PartnerCommission":6.5,
   "NetDonation":89.25,
   "PaymentStatus":"Paid By Check",
   "FirstName":"FirstName",
   "LastName":"LastName",
   "CardLast4":"1234",
   "DonorMessage":"Donor Message",
   "PaymentId":444,
   "PaymentLineId":555,
   "CustomerPledgeId":"4939000",
   "CustomerCampaignName":"A Test Campaign",
   "DonationSource":"Donation Source",
   "DatePosted":"1\/21\/2014",
   "DateSettled":"1\/22\/2014"
}</code>

Responding to a Webhook

To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Given any response outside the 200 range, FirstGiving will continue trying to send the webhook every few minutes for 3 days. After 3 days, we’ll mark the request as failed and stop trying.

Testing Webhooks

You can post a test payload from within your FirstGiving dashboard. Login and navigate to ‘Webhooks’ in the left column. If you don’t have any test webhook URLs defined, you’ll have to define one first. Then, hit test and we will post a test payload to the endpoint. The endpoint configuration will not be saved unless you press save. If you don’t have an application set up to receive webhooks but want to samples requests, we suggest using a service like RequestBin to inspect the requests we send.