FirstGiving Donation API Documentation

Charity Search API - v2.0

The Charity Search API is a public search API for Nonprofits (National Chapters) for which FirstGiving can process donations. 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:'https://graphapi.firstgiving.com/v2/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; required to process any transactions using the FirstGiving Donation API
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 State
postal_code 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

Note: While organization_uuid, organization_name, and address fields will always have data, others, such as phone_number and category_code, are not always available.

Retrieving a Charity by EIN

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

Request

GET https://graphapi.firstgiving.com/v2/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 matching functionality.

An exact match query takes the form of: http://graphapi.firstgiving.com/v2/list/organization?q=organization_name:{organization name}

Partial name search queries can be made by appending an asterisk ‘*’ to the beginning and/or end of the name: http://graphapi.firstgiving.com/v2/list/organization?q=organization_name:*{organization name}*

 

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.

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:

https://graphapi.firstgiving.com/v2/list/organization?q=organization_name:bat*&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:

https://graphapi.firstgiving.com/v2/list/organization?q=organization_name:bat*&count=on

 

Custom Query Separators

The list query method uses the word ‘AND’ as a 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:

https://graphapi.firstgiving.com/v2/list/organization?q=organization_name:american%20AND%20african*%20XZSY%20&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’. E.g.:

http://graphapi.firstgiving.com/v2/list/organization?q=organization_name:bat*&list_by_id=on

 

 

Retrieving a Charity by ID

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

Example:

GET http://graphapi.firstgiving.com/v2/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):

{
"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"
}
}

 

 

 
Client Session Authentication
Endpoint URL:

https://{environmentVariable}.firstgiving.com/security/clientsession

Environment Variables:

qa-api - QA Environment
api - Production Environment

REST HTTP Method: POST
Authentication: none
URL Parameters: applicationKey
securityToken

URL Parameter Definitions:

Parameter Definition Notes Required?
applicationKey Provided by Frontstream upon registration of the application. - Yes
securityToken Provided by Frontstream upon registration of the application. - Yes

 

Example Success Response:

HTTP Response: 200 OK

Relevant Header Values (applicable for all response types):

Jg-Execution-Time Time in milliseconds the transaction took to complete from when the original request arrived to when the response was sent by the FirstGiving server.
Jg-Environment Indicates which environment the request came from; possible values: 'staging', 'qa', 'production'.
Jg-Response-Signature Cryptographic signature to be used with the Verify endpoint.
X-Powered-By Indicates which FirstGiving server the transaction was processed on. Recommended to log and provide with any request for support.

Success Response Body:

<?xml version="1.0" encoding="utf-8"?>
<firstGivingClientSession xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<clientSessionResponse acknowledgement="Success">
<clientSessionId>9kyglAsESADicA4jLPz7Wll6bH0NCyF1oR83En86VancDbIsWLhscRhqwpzr9zknaJl7lOIi6tFCviby0+ehvx6yS6CwM2/dH0C5mtcV+G9/HGgCSQPpLlJ94qUEt4C5LbnvIGj9EcHABNryy20LKC2QcihdWGv5gf9cO8FlXRO0XuYZm2Pp4hAVZq2KMGZD</clientSessionId>
</clientSessionResponse>
</firstGivingClientSession>

Response Data:

  Description Use
clientSessionId A unique, one-time-use token for endpoints that handle credit card data. Expires 5 hours after generation. Authenticates to the Credit Card, Card On File, and Recurring Billing endpoints.

 

Credit Card Transaction
Endpoint URL: https://{environmentVariable}.firstgiving.com/donation/creditcard
Environment Variables: qa-api - QA Environment
  api - Production Environment
REST HTTP Method: POST
Required Headers: Content-Type:application/xml
Authentication Header: CLIENT_SESSION:
URL Parameters:

none

Example Body Parameters:

<donation>
<amount>100.00</amount>
<billToAddressLine1></billToAddressLine1>
<billToAddressLine2 />
<billToAddressLine3 />
<billToCity>Test</billToCity>
<billToState>VA</billToState>
<billToZip>10001</billToZip>
<billToCountry>US</billToCountry>
<billToEmail>test@test.test</billToEmail>
<billToFirstName>TestFirst</billToFirstName>
<billToLastName>TestLast</billToLastName>
<billToMiddleName>TestMiddle</billToMiddleName>
<billToTitle>Dr.</billToTitle>
<billToPhone>555-555-5555</billToPhone>
<campaignName>FG Test Transaction Please Ignore</campaignName>
<ccCardValidationNum>150</ccCardValidationNum>
<ccExpDateMonth>01</ccExpDateMonth>
<ccExpDateYear>22</ccExpDateYear>
<ccNumber>5454545454545454</ccNumber>
<ccType>MC</ccType>
<charityId>00000000-0000-0000-0000-000000000000</charityId>
<commissionRate>0.0</commissionRate>
<currencyCode>USD</currencyCode>
<description>Test Transaction</description>
<donationMessage>Hello</donationMessage>
<eventId>12345</eventId>
<fundraiserId>67890</fundraiserId>
<honorMemoryName>Honor Memory</honorMemoryName>
<orderId>24680</orderId>
<pledgeId>1234567</pledgeId>
<remoteAddr>127.0.0.1</remoteAddr>
<allowEmailContact>Yes</allowEmailContact>
<allowMailContact>No</allowMailContact>
<allowPhoneContact></allowPhoneContact>
</donation>

Body Parameter Definitions:

 

Parameter Description Notes Required?
amount The amount of currency units to be donated. Should be in decimal format; minimum value: 1.00 Yes
currencyCode The currency code for the currency that describes the number of units to withdraw from the donor’s account. Must always be 'USD'. Yes
billToAddressLine1 Address line 1 for the cardholder's bill to address. Max Length: 255 characters. Yes
billToAddressLine2 Address line 2 for the cardholder's bill to address. Max Length: 255 characters. No
billToAddressLine3 Address line 3 for the cardholder's bill to address. Max Length: 255 characters. No
billToCity City of the cardholder's bill to address. Max Length: 35 characters. Yes
billToState State of the cardholder's bill to address. When the billToCountry is US, this is required to be the 2-character ISO state code (i.e. FL, NY, etc. instead of "Florida" or "New York"). Max Length: 2 characters when US; otherwise 30 characters Only when billToCountry is US
billToZip ZIP Code/Postal Code of the cardholder's bill to address. Max Length: 20 characters Yes
billToCountry Two-character country code of the cardholder's bill to address. Accepts any ISO 3166-1 Alpha-2 code. Yes
billToEmail Email address that corresponds to the customer bill to address. A receipt will be sent to this email address for successful transactions. Max Length: 100 characters. Yes
billToFirstName The donor's first name. Max Length: 100 characters. Yes
billToMiddleName The donor's middle name. Max Length: 100 characters. No
billToLastName The donor's last name. Max Length: 100 characters. Yes
billToTitle The donor's prefix/title, generally "Dr.", "Mr.", "Ms.", etc.. Max Length: 10 characters. No
billToPhone The cardholder's phone number. Max Length: 20 characters No
ccType Card brand being used for the transaction. Accepted Card Types:
VI - Visa
MC - MasterCard
DI - Discover
AX - American Express
Yes
ccNumber The donor's credit card number. 15 (AX) or 16 (VI, MC, DI) digits Yes
ccExpDateMonth The donor's credit card's Expiration Date Month Must be 2 digits, i.e. 12, 02, 06, etc. Yes
ccExpDateYear The donor's credit card's Expiration Date Year Must be 4 digits, i.e. 2077 Yes
ccCardValidationNum The donor's credit card's security number. Must be 3 (VI, MC, DI) or 4 (AX) digits. Yes
charityId The organization_uuid value returned by the FirstGiving Charity Graph API.   Yes
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. Max Length: 250 characters No
description A short description for the donation.   Yes
honorMemoryName The name of an individual or organization that a donor is honoring or making the donation in memory of. Max Length: 50 No
donationMessage Message to the charity from the donor associated with the honorarium. Max Length: 250 No
eventId An identifier provided by FirstGiving which identifies the FirstGiving-based Event associated with the donation.   No
fundraiserId A universally unique ID which identifies the user account that was responsible for the donation collected.   No
orderId A universally unique ID generated by the integrator allowing them to identify the donation in their system.   No
pledgeId An integrator-defined field used primarily to prevent duplicate transactions. If an API call is made using a pledgeId that has already been used by the integrator, then it will be automatically rejected prior to processing the credit card. This value also persists to charity reporting, intended to allow the charity to associate it to a transaction in the integrator's system. Max Length: 50 Yes
remoteAddr The IP address of the donor. Max Length: 15 Yes
commissionRate The Retail Transaction Fee percentage to be withheld from the donation. This must be less than the Maximum Fee (FirstGiving Fees + Licensee Profit Percentage) configured at the time of setup (please review your integrator contract for details). The FirstGiving Fees of 4.25% will always be charged regardless of the value passed. For example, passing “9.25” with a $100.00 transaction will have $9.25 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. If the value passed is less than 4.25, it will default to 4.25. If this value is above the maximum or null, the maximum is used by default.   No

 

 

Example Success Response:

HTTP Response: 200 OK

Relevant Header Values (applicable for all response types):

Jg-Execution-Time Time in milliseconds the transaction took to complete from when the original request arrived to when the response was sent by the FirstGiving server.
Jg-Environment Indicates which environment the request came from; possible values: 'staging', 'qa', 'production'.
Jg-Response-Signature Cryptographic signature to be used with the Verify endpoint.
X-Powered-By Indicates which FirstGiving server the transaction was processed on. Recommended to log and provide with any request for support.

Success Response Body:

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Success">
<transactionId>a-e8f8a121ce4ea1af1a8e5a</transactionId>
<donationId>123456789</donationId>
</firstGivingResponse>
</firstGivingDonationApi>

Response Data:

  Description Use
TransactionId Unique identifier within the FirstGiving Donation API. Required for both the Transaction Lookup and Refund API endpoints, as well as being listed within API Partner Reporting.
DonationId Unique identifier within FirstGiving's internal tools. Required for the Refund API endpoint, and the most useful identifier our Support team can use to assist you with issues involving the transaction.

 

Possible Error Responses:

If the JG_APPLICATIONKEY and/or JG_SECURITYTOKEN are invalid:

HTTP Response: 401 Unauthorized

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="Bad JG_APPLICATIONKEY and JG_SECURITYTOKEN."/>
</firstGivingDonationApi>

If a transaction is declined:

HTTP Response: 500 Internal Server Error

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="There was a problem processing the donation at the gateway." verboseErrorMessage="Issue Authorization response received from the Litle gateway while processing order a-e8f8a121ce4ea1af1a8e5a, Gateway Response: Invalid Account Number"/>
</firstGivingDonationApi>

The above friendly and verbose error messages can be different depending on the response from the payment processing gateway; here are all the possible responses:

Error Type Friendly Error Message Verbose Error Message Explanation
AVS Failure The transaction failed. Please check the card information and try again. AVS failure AVS did not return a full match on the address provided.
Insufficient Funds An error occurred. Please check your input and try again. Insufficient Funds Processor returned Insufficient Funds as the decline reason.
Do Not Honor An error occurred. Please check your input and try again. Do Not Honor Processor returned Do Not Honor as the decline reason.
CVV Declines An error occurred. Please check your input and try again. Decline CVV2/CID Fail CVV/CID mismatch from the processor.
Generic Decline An error occurred. Please check your input and try again. Generic Decline

Decline for reason not handled by any other error.

Invalid Account Number An error occurred. Please check your input and try again. Invalid Account Number Credit Card Number (last 10) provided isn't valid.
Invalid Issuer An error occurred. Please check your input and try again. No Such Issuer BIN (first 6 digits of the card) isn't valid.
Issuer Issue An error occurred. Please check your input and try again. Call Issuer Decline with request for cardholder to contact issuer.
Expired Card An error occurred. Please check your input and try again. Expired Card Decline due to expiration date being in the past, regardless of what was entered in the payment page.
Restricted Card An error occurred. Please check your input and try again. Restricted Card Card declined for reason "Restricted Card" at the processor.
Lost Card An error occurred. Please check your input and try again. Lost/Stolen Card Decline due to card being reported as lost or stolen to the issuer.
Invalid Transaction An error occurred. Please check your input and try again. Invalid Transaction Card declined for reason "Invalid Transaction" at the processor.
Not Permitted An error occurred. Please check your input and try again. Cardholder transaction not permitted Card declined for reason "Not Permitted" at the processor.

For all of the above failure reasons, these are legitimate card declines directly from the credit card processor and not errors from within FirstGiving. The cardholder will need to contact their card issuer; FirstGiving will not be able to assist them as our representatives do not have access to this information.

Storing a Card On File
Endpoint URL: https://{environmentVariable}.firstgiving.com/donation/cardonfile
Environment Variables: qa-api - QA Environment
  api - Production Environment
REST HTTP Method: POST
Required Headers: Content-Type:application/xml
Authentication Header: CLIENT_SESSION:
URL Parameters:

none

Example Body Parameters:

<cardOnFile>
<accountName>Test Cardholder</accountName>
<billToAddressLine1></billToAddressLine1>
<billToAddressLine2 />
<billToAddressLine3 />
<billToCity>Test</billToCity>
<billToState>VA</billToState>
<billToZip>10001</billToZip>
<billToCountry>US</billToCountry>
<billToEmail>test@test.test</billToEmail>
<billToFirstName>TestFirst</billToFirstName>
<billToLastName>TestLast</billToLastName>
<billToMiddleName>TestMiddle</billToMiddleName>
<billToTitle>Dr.</billToTitle>
<billToPhone>555-555-5555</billToPhone>
<ccCardValidationNum>150</ccCardValidationNum>
<ccExpDateMonth>01</ccExpDateMonth>
<ccExpDateYear>22</ccExpDateYear>
<ccNumber>5454545454545454</ccNumber>
<ccType>MC</ccType>
<remoteAddr>127.0.0.1</remoteAddr>
</cardOnFile>

 

Body Parameter Definitions:

Parameter Description Notes Required?
accountName The name printed on the credit card. Max Length: 255 characters. Yes
billToAddressLine1 Address line 1 for the cardholder's bill to address. Max Length: 255 characters. Yes
billToAddressLine2 Address line 2 for the cardholder's bill to address. Max Length: 255 characters. No
billToAddressLine3 Address line 3 for the cardholder's bill to address. Max Length: 255 characters. No
billToCity City of the cardholder's bill to address. Max Length: 35 characters. Yes
billToState State of the cardholder's bill to address. When the billToCountry is US, this is required to be the 2-character ISO state code (i.e. FL, NY, etc. instead of "Florida" or "New York"). Max Length: 2 characters when US; otherwise 30 characters Only when billToCountry is US
billToZip ZIP Code/Postal Code of the cardholder's bill to address. Max Length: 20 characters Yes
billToCountry Two-character country code of the cardholder's bill to address. Accepts any ISO 3166-1 Alpha-2 code. Yes
billToEmail Email address that corresponds to the customer bill to address. A receipt will be sent to this email address for successful transactions. Max Length: 100 characters. Yes
billToFirstName The donor's first name. Max Length: 100 characters. Yes
billToMiddleName The donor's middle name. Max Length: 100 characters. No
billToLastName The donor's last name. Max Length: 100 characters. Yes
billToTitle The donor's prefix/title, generally "Dr.", "Mr.", "Ms.", etc.. Max Length: 10 characters. No
billToPhone The cardholder's phone number. Max Length: 20 characters No
ccType Card brand being used for the transaction. Accepted Card Types:
VI - Visa
MC - MasterCard
DI - Discover
AX - American Express
Yes
ccNumber The donor's credit card number. 15 (AX) or 16 (VI, MC, DI) digits Yes
ccExpDateMonth The donor's credit card's Expiration Date Month Must be 2 digits, i.e. 12, 02, 06, etc. Yes
ccExpDateYear The donor's credit card's Expiration Date Year Must be 4 digits, i.e. 2077 Yes
ccCardValidationNum The donor's credit card's security number. Must be 3 (VI, MC, DI) or 4 (AX) digits. Yes
remoteAddr The IP address of the donor. Max Length: 15 Yes

Success Response Body:

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<firstGivingResponse acknowledgement="Success">
<cardOnFileId>00000000-0000-0000-0000-000000000000</cardOnFileId>
</firstGivingResponse>
</firstGivingDonationApi>

NOTE: Tokenizing a card successfully does not run any sort of pre-authorization or validation of the credit card data provided past validating the credit card number's checksum and ensuring the expiration date is not in the past; transactions processed using the cardOnFileId may still decline for valid reasons in the future if incorrect data is provided by the cardholder (CVV Decline, AVS Decline, etc.) or the card is otherwise not valid (Insufficient Funds, Lost Card, Invalid Account Number, etc.).

 

Possible Error Responses:

 

If a required field is missing:

HTTP Response: 400 Bad Request

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="Missing required params: ccNumber,ccType,ccExpDateYear,ccExpDateMonth,ccCardValidationNum,billToFirstName,billToLastName,billToAddressLine1,billToCity,billToZip,billToCountry,billToEmail,remoteAddr,accountName"/>
</firstGivingDonationApi>

 

 

Credit Card Transaction using Card On File
Endpoint URL: https://{environmentVariable}.firstgiving.com/donation/creditcard
Environment Variables: qa-api - QA Environment
  api - Production Environment
REST HTTP Method: POST
Required Headers: Content-Type:application/xml
Authentication Header: CLIENT_SESSION:
URL Parameters:

none

Example Body Parameters:

<donation>
<cardOnFileId>cardOnFileId returned from Card On File Endpoint</cardOnFileId>
<amount>100.00</amount>
<campaignName>FG Test Transaction Please Ignore</campaignName>
<charityId>00000000-0000-0000-0000-000000000000</charityId>
<commissionRate>0.0</commissionRate>
<currencyCode>USD</currencyCode>
<description>Test Transaction</description>
<donationMessage>Hello</donationMessage>
<eventId>12345</eventId>
<fundraiserId>67890</fundraiserId>
<honorMemoryName>Honor Memory</honorMemoryName>
<orderId>24680</orderId>
<pledgeId>1234567</pledgeId>
<remoteAddr>127.0.0.1</remoteAddr>
<allowEmailContact>Yes</allowEmailContact>
<allowMailContact>No</allowMailContact>
<allowPhoneContact></allowPhoneContact>
</donation>

Body Parameter Definitions:

 

Parameter Description Notes Required?
cardOnFileId The cardOnFileId contained in the success response from the Card On File Endpoint. Will always be a GUID Yes
amount The amount of currency units to be donated. Should be in decimal format; minimum value: 1.00 Yes
currencyCode The currency code for the currency that describes the number of units to withdraw from the donor’s account. Must always be 'USD'. Yes
charityId The organization_uuid value returned by the FirstGiving Charity Graph API.   Yes
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. Max Length: 250 characters No
description A short description for the donation.   Yes
honorMemoryName The name of an individual or organization that a donor is honoring or making the donation in memory of. Max Length: 50 No
donationMessage Message to the charity from the donor associated with the honorarium. Max Length: 250 No
eventId An identifier provided by FirstGiving which identifies the FirstGiving-based Event associated with the donation.   No
fundraiserId A universally unique ID which identifies the user account that was responsible for the donation collected.   No
orderId A universally unique ID generated by the integrator allowing them to identify the donation in their system.   No
pledgeId An integrator-defined field used primarily to prevent duplicate transactions. If an API call is made using a pledgeId that has already been used by the integrator, then it will be automatically rejected prior to processing the credit card. This value also persists to charity reporting, intended to allow the charity to associate it to a transaction in the integrator's system. Max Length: 50 Yes
remoteAddr The IP address of the donor. Max Length: 15 Yes
commissionRate The Retail Transaction Fee percentage to be withheld from the donation. This must be less than the Maximum Fee (FirstGiving Fees + Licensee Profit Percentage) configured at the time of setup (please review your integrator contract for details). The FirstGiving Fees of 4.25% will always be charged regardless of the value passed. For example, passing “9.25” with a $100.00 transaction will have $9.25 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. If the value passed is less than 4.25, it will default to 4.25. If this value is above the maximum or null, the maximum is used by default.   No

 

 

Example Success Response:

HTTP Response: 200 OK

Relevant Header Values (applicable for all response types):

Jg-Execution-Time Time in milliseconds the transaction took to complete from when the original request arrived to when the response was sent by the FirstGiving server.
Jg-Environment Indicates which environment the request came from; possible values: 'staging', 'qa', 'production'.
Jg-Response-Signature Cryptographic signature to be used with the Verify endpoint.
X-Powered-By Indicates which FirstGiving server the transaction was processed on. Recommended to log and provide with any request for support.

Success Response Body:

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Success">
<transactionId>a-e8f8a121ce4ea1af1a8e5a</transactionId>
<donationId>123456789</donationId>
</firstGivingResponse>
</firstGivingDonationApi>

Response Data:

  Description Use
TransactionId Unique identifier within the FirstGiving Donation API. Required for both the Transaction Lookup and Refund API endpoints, as well as being listed within API Partner Reporting.
DonationId Unique identifier within FirstGiving's internal tools. Required for the Refund API endpoint, and the most useful identifier our Support team can use to assist you with issues involving the transaction.

 

Possible Error Responses:


If a transaction is declined:

HTTP Response: 500 Internal Server Error

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="There was a problem processing the donation at the gateway." verboseErrorMessage="Issue Authorization response received from the Litle gateway while processing order a-e8f8a121ce4ea1af1a8e5a, Gateway Response: Invalid Account Number"/>
</firstGivingDonationApi>

The above friendly and verbose error messages can be different depending on the response from the payment processing gateway; here are all the possible responses:

Error Type Friendly Error Message Verbose Error Message Explanation
AVS Failure The transaction failed. Please check the card information and try again. AVS failure AVS did not return a full match on the address provided.
Insufficient Funds An error occurred. Please check your input and try again. Insufficient Funds Processor returned Insufficient Funds as the decline reason.
Do Not Honor An error occurred. Please check your input and try again. Do Not Honor Processor returned Do Not Honor as the decline reason.
CVV Declines An error occurred. Please check your input and try again. Decline CVV2/CID Fail CVV/CID mismatch from the processor.
Generic Decline An error occurred. Please check your input and try again. Generic Decline

Decline for reason not handled by any other error.

Invalid Account Number An error occurred. Please check your input and try again. Invalid Account Number Credit Card Number (last 10) provided isn't valid.
Invalid Issuer An error occurred. Please check your input and try again. No Such Issuer BIN (first 6 digits of the card) isn't valid.
Issuer Issue An error occurred. Please check your input and try again. Call Issuer Decline with request for cardholder to contact issuer.
Expired Card An error occurred. Please check your input and try again. Expired Card Decline due to expiration date being in the past, regardless of what was entered in the payment page.
Restricted Card An error occurred. Please check your input and try again. Restricted Card Card declined for reason "Restricted Card" at the processor.
Lost Card An error occurred. Please check your input and try again. Lost/Stolen Card Decline due to card being reported as lost or stolen to the issuer.
Invalid Transaction An error occurred. Please check your input and try again. Invalid Transaction Card declined for reason "Invalid Transaction" at the processor.
Not Permitted An error occurred. Please check your input and try again. Cardholder transaction not permitted Card declined for reason "Not Permitted" at the processor.

For all of the above failure reasons, these are legitimate card declines directly from the credit card processor and not errors from within FirstGiving. The cardholder will need to contact their card issuer; FirstGiving will not be able to assist them as our representatives do not have access to this information.

Requesting Refunds
Endpoint URL: https://{environmentvariable}.firstgiving.com/transaction/refundrequest
Environment Variables:

donatenowstaging - Staging Environment
qa-api - QA Environment
api - Production Environment

REST HTTP Method: GET
Authentication: Uses JG_APPLICATIONKEY and JG_SECURITYTOKEN headers
Required Headers:

JG_APPLICATIONKEY
JG_SECURITYTOKEN

URL Parameters: transactionId
donationId
tranType

URL Parameter Definitions:

Parameter Description Notes Required?
transactionId Unique identifier within the FirstGiving Donation API. Returned by the Donation API for any successful transaction. The endpoint requires a transactionId OR donationId, though both can be provided as long as they belong to the same transaction. Yes*
donationId Unique identifier for FirstGiving's internal tools. Returned by the Donation API for any successful transaction. The endpoint requires a transactionId OR donationId, though both can be provided as long as they belong to the same transaction. Yes*
tranType "REFUNDREQUEST". This will always be 'REFUNDREQUEST'; no other values are supported. Yes

 

Example Success Response:

HTTP Response: 200 OK

Relevant Header Values (applicable for all response types):

Jg-Execution-Time Time in milliseconds the transaction took to complete from when the original request arrived to when the response was sent by the FirstGiving server.
Jg-Environment Indicates which environment the request came from; possible values: 'staging', 'qa', 'production'.
Jg-Response-Signature Cryptographic signature to be used with the Verify endpoint.
X-Powered-By Indicates which FirstGiving server the transaction was processed on. Recommended to log and provide with any request for support.

Success Response Body:

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="REFUND_REQUESTED_AWAITING_REFUND">
<transactionId>a-1b23f4f567de8f90b12e34</transactionId>
<donationId>12345678</donationId>
</firstGivingResponse>
</firstGivingDonationApi>

 

Possible Error Responses:

If the transaction is not in a status that can be refunded:

HTTP Response: 500 Internal Server Error

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="Donation process status unsupported for refund request" verboseErrorMessage="Donation process status unsupported for refund request"/>
</firstGivingDonationApi>

 

If the transactionId or donationId does not exist or is in an invalid format:

HTTP Response: 400 Bad Request

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="The requested transaction was not found."/>
</firstGivingDonationApi>

 

If 'REFUNDREQUEST' is omitted or another value is provided for tranType:

HTTP Response: 400 Bad Request

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="Invalid tranType value. Valid format tranType=REFUNDREQUEST"/>
</firstGivingDonationApi>

 

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

Recurring Credit Card Profiles
Endpoint URL: https://{environmentVariable}.firstgiving.com/donation/recurringcreditcardprofile
Environment Variables: qa-api - QA Environment
  api - Production Environment
REST HTTP Method: POST
Required Headers: Content-Type:application/xml
Authentication Header: CLIENT_SESSION:
URL Parameters:

none

Example Body Parameters:

<recurringDonation>
<recurringBillingFrequency>MONTHLY</recurringBillingFrequency>
<recurringBillingTerm>12</recurringBillingFrequency>
<amount>100.00</amount>
<billToAddressLine1></billToAddressLine1>
<billToAddressLine2 />
<billToAddressLine3 />
<billToCity>Test</billToCity>
<billToState>VA</billToState>
<billToZip>10001</billToZip>
<billToCountry>US</billToCountry>
<billToEmail>test@test.test</billToEmail>
<billToFirstName>TestFirst</billToFirstName>
<billToLastName>TestLast</billToLastName>
<billToMiddleName>TestMiddle</billToMiddleName>
<billToTitle>Dr.</billToTitle>
<billToPhone>555-555-5555</billToPhone>
<campaignName>FG Test Transaction Please Ignore</campaignName>
<ccCardValidationNum>150</ccCardValidationNum>
<ccExpDateMonth>01</ccExpDateMonth>
<ccExpDateYear>22</ccExpDateYear>
<ccNumber>5454545454545454</ccNumber>
<ccType>MC</ccType>
<charityId>00000000-0000-0000-0000-000000000000</charityId>
<commissionRate>0.0</commissionRate>
<currencyCode>USD</currencyCode>
<description>Test Transaction</description>
<donationMessage>Hello</donationMessage>
<eventId>12345</eventId>
<fundraiserId>67890</fundraiserId>
<honorMemoryName>Honor Memory</honorMemoryName>
<orderId>24680</orderId>
<pledgeId>1234567</pledgeId>
<remoteAddr>127.0.0.1</remoteAddr>
<allowEmailContact>Yes</allowEmailContact>
<allowMailContact>No</allowMailContact>
<allowPhoneContact></allowPhoneContact>
</recurringDonation>

Body Parameter Definitions:

 

Parameter Description Notes Required?
recurringBillingFrequency The type of recurring schedule to be used by the recurring billing engine. Valid values: MONTHLY (every month), QUARTERLY (every 3 months), SEMIYEARLY (every 6 months), YEARLY (every 12 months). Billing recurs on the same numeric date that the first donation is made; if the donation occurs on a numeric date that does not exist in other months, then billing will recur on the last day of the month. Example: If recurring billing profile is first billed on March 31st, then it will recur on April 30th, May 31st, June 30th, etc.. See Additional Notes below for more details. Uppercase is Required Yes
recurringBillingTerm A number used to indicate how many times the profile should be billed. Example: A frequency of 'MONTHLY', with a term of '6', and with an amount of '10.00' passed into the API would result in the profile being billed $10.00 per month for 6 months, for an overall total of $60.00 billed to the donor. Integer values only; '0' indicates it should recur indefinitely Yes
amount The amount of currency units to be donated. Should be in decimal format; minimum value: 1.00 Yes
currencyCode The currency code for the currency that describes the number of units to withdraw from the donor’s account. Must always be 'USD'. Yes
billToAddressLine1 Address line 1 for the cardholder's bill to address. Max Length: 255 characters. Yes
billToAddressLine2 Address line 2 for the cardholder's bill to address. Max Length: 255 characters. No
billToAddressLine3 Address line 3 for the cardholder's bill to address. Max Length: 255 characters. No
billToCity City of the cardholder's bill to address. Max Length: 35 characters. Yes
billToState State of the cardholder's bill to address. When the billToCountry is US, this is required to be the 2-character ISO state code (i.e. FL, NY, etc. instead of "Florida" or "New York"). Max Length: 2 characters when US; otherwise 30 characters Only when billToCountry is US
billToZip ZIP Code/Postal Code of the cardholder's bill to address. Max Length: 20 characters Yes
billToCountry Two-character country code of the cardholder's bill to address. Accepts any ISO 3166-1 Alpha-2 code. Yes
billToEmail Email address that corresponds to the customer bill to address. A receipt will be sent to this email address for successful transactions. Max Length: 100 characters. Yes
billToFirstName The donor's first name. Max Length: 100 characters. Yes
billToMiddleName The donor's middle name. Max Length: 100 characters. No
billToLastName The donor's last name. Max Length: 100 characters. Yes
billToTitle The donor's prefix/title, generally "Dr.", "Mr.", "Ms.", etc.. Max Length: 10 characters. No
billToPhone The cardholder's phone number. Max Length: 20 characters No
ccType Card brand being used for the transaction. Accepted Card Types:
VI - Visa
MC - MasterCard
DI - Discover
AX - American Express
Yes
ccNumber The donor's credit card number. 15 (AX) or 16 (VI, MC, DI) digits Yes
ccExpDateMonth The donor's credit card's Expiration Date Month Must be 2 digits, i.e. 12, 02, 06, etc. Yes
ccExpDateYear The donor's credit card's Expiration Date Year Must be 4 digits, i.e. 2077 Yes
ccCardValidationNum The donor's credit card's security number. Must be 3 (VI, MC, DI) or 4 (AX) digits. Yes
charityId The organization_uuid value returned by the FirstGiving Charity Graph API.   Yes
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. Max Length: 250 characters No
description A short description for the donation.   Yes
honorMemoryName The name of an individual or organization that a donor is honoring or making the donation in memory of. Max Length: 50 No
donationMessage Message to the charity from the donor associated with the honorarium. Max Length: 250 No
eventId An identifier provided by FirstGiving which identifies the FirstGiving-based Event associated with the donation.   No
fundraiserId A universally unique ID which identifies the user account that was responsible for the donation collected.   No
orderId A universally unique ID generated by the integrator allowing them to identify the donation in their system.   No
pledgeId An integrator-defined field used primarily to prevent duplicate transactions. If an API call is made using a pledgeId that has already been used by the integrator, then it will be automatically rejected prior to processing the credit card. This value also persists to charity reporting, intended to allow the charity to associate it to a transaction in the integrator's system. Max Length: 50 Yes
remoteAddr The IP address of the donor. Max Length: 15 Yes
commissionRate The Retail Transaction Fee percentage to be withheld from the donation. This must be less than the Maximum Fee (FirstGiving Fees + Licensee Profit Percentage) configured at the time of setup (please review your integrator contract for details). The FirstGiving Fees of 4.25% will always be charged regardless of the value passed. For example, passing “9.25” with a $100.00 transaction will have $9.25 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. If the value passed is less than 4.25, it will default to 4.25. If this value is above the maximum or null, the maximum is used by default.   No

 

Additional Notes:

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.

 

Example Success Response:

HTTP Response: 200 OK

Relevant Header Values (applicable for all response types):

Jg-Execution-Time Time in milliseconds the transaction took to complete from when the original request arrived to when the response was sent by the FirstGiving server.
Jg-Environment Indicates which environment the request came from; possible values: 'staging', 'qa', 'production'.
Jg-Response-Signature Cryptographic signature to be used with the Verify endpoint.
X-Powered-By Indicates which FirstGiving server the transaction was processed on. Recommended to log and provide with any request for support.

Success Response Body:

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Success">
<recurringDonationProfileId>1a2b34cd5f678</recurringDonationProfileId>
</firstGivingResponse>
</firstGivingDonationApi>

Response Data:

  Description Use
recurringDonationProfileId Unique identifier for the recurring billing profile within the FirstGiving Donation API. Useful for support requests having to do with recurring billing, but has no use within the API itself.


Possible Error Responses:

If the JG_APPLICATIONKEY and/or JG_SECURITYTOKEN are invalid:

HTTP Response: 401 Unauthorized

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="Bad JG_APPLICATIONKEY and JG_SECURITYTOKEN."/>
</firstGivingDonationApi>

 

If a duplicate recurring billing profile is found:

HTTP Response: 500 Internal Server Error

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="There was a problem processing your request." verboseErrorMessage="Duplicate recurring profile request detected."/>
</firstGivingDonationApi>

 

If a transaction is declined:

HTTP Response: 500 Internal Server Error

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="There was a problem processing the donation at the gateway." verboseErrorMessage="Issue Authorization response received from the Litle gateway while processing order a-e8f8a121ce4ea1af1a8e5a, Gateway Response: Invalid Account Number"/>
</firstGivingDonationApi>

The above friendly and verbose error messages can be different depending on the response from the payment processing gateway; here are all the possible responses:

Error Type Friendly Error Message Verbose Error Message Explanation
AVS Failure The transaction failed. Please check the card information and try again. AVS failure AVS did not return a full match on the address provided.
Insufficient Funds An error occurred. Please check your input and try again. Insufficient Funds Processor returned Insufficient Funds as the decline reason.
Do Not Honor An error occurred. Please check your input and try again. Do Not Honor Processor returned Do Not Honor as the decline reason.
CVV Declines An error occurred. Please check your input and try again. Decline CVV2/CID Fail CVV/CID mismatch from the processor.
Generic Decline An error occurred. Please check your input and try again. Generic Decline

Decline for reason not handled by any other error.

Invalid Account Number An error occurred. Please check your input and try again. Invalid Account Number Credit Card Number (last 10) provided isn't valid.
Invalid Issuer An error occurred. Please check your input and try again. No Such Issuer BIN (first 6 digits of the card) isn't valid.
Issuer Issue An error occurred. Please check your input and try again. Call Issuer Decline with request for cardholder to contact issuer.
Expired Card An error occurred. Please check your input and try again. Expired Card Decline due to expiration date being in the past, regardless of what was entered in the payment page.
Restricted Card An error occurred. Please check your input and try again. Restricted Card Card declined for reason "Restricted Card" at the processor.
Lost Card An error occurred. Please check your input and try again. Lost/Stolen Card Decline due to card being reported as lost or stolen to the issuer.
Invalid Transaction An error occurred. Please check your input and try again. Invalid Transaction Card declined for reason "Invalid Transaction" at the processor.
Not Permitted An error occurred. Please check your input and try again. Cardholder transaction not permitted Card declined for reason "Not Permitted" at the processor.

For all of the above failure reasons, these are legitimate card declines directly from the credit card processor and not errors from within FirstGiving. The cardholder will need to contact their card issuer; FirstGiving will not be able to assist them as our representatives do not have access to this information.

Transaction List
Endpoint URL: https://{environmentvariable}.firstgiving.com/transaction/list
Environment Variables: qa-api - QA Environment
api - Production Environment
REST HTTP Method: GET
Authentication Headers:

JG_APPLICATIONKEY
JG_SECURITYTOKEN

Querystring Parameters: date_from
page_size
page
count

Querystring Parameter Definitions:

Parameter Description Notes Required?
date_from Defines the oldest transaction date of any transactions that should be returned. Epoch/Unix Timestamp Integer Yes
page_size Number of transactionIds to be returned per page. Max: 100 Yes
page The page number to return. Starts at 1 Yes
count Specifies whether to return a count of transactions. Specify 'on', else do not include in the querystring. No

 

Example Success Response:

HTTP Response: 200 OK

Relevant Header Values (applicable for all response types):

Jg-Execution-Time Time in milliseconds the transaction took to complete from when the original request arrived to when the response was sent by the FirstGiving server.
Jg-Environment Indicates which environment the request came from; possible values: 'staging', 'qa', 'production'.
Jg-Response-Signature Cryptographic signature to be used with the Verify endpoint.
X-Powered-By Indicates which FirstGiving server the transaction was processed on. Recommended to log and provide with any request for support.

Success Response Body:

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Success">
<transactions>
<transactionId>a-1a23b4c567de8f90a12b34</transactionId>
<transactionId>a-cd5e6f789ab0123456c78d</transactionId>
<transactionId>a-e90f1a234567b890c12d34</transactionId>
<transactionId>a-e567890f1a234b567890c1</transactionId>
<transactionId>a-234567de8f901a23b4567c</transactionId>
</transactions>
</firstGivingResponse>
</firstGivingDonationApi>

Note: The list of transactionIds will be paged and returned in descending chronological order, i.e. the most recent transaction will be listed first.

Response Data:

  Description Use
TransactionId Unique identifier within the FirstGiving Donation API. Required for both the Transaction Lookup and Refund API endpoints, as well as being listed within API Partner Reporting.

 

Possible Error Responses:

If the JG_APPLICATIONKEY and/or JG_SECURITYTOKEN are invalid:

HTTP Response: 401 Unauthorized

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="Bad JG_APPLICATIONKEY and JG_SECURITYTOKEN."/>
</firstGivingDonationApi>

If the page or page_size value(s) are less than 1:

HTTP Response: 400 Bad Request

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="page error Integer cannot be less than 1"/>
</firstGivingDonationApi>

 

If the page_size parameter is greater than 100:

HTTP Response: 400 Bad Request

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="page_size error Cannot be greater than 100"/>
</firstGivingDonationApi>

 

Transaction Details
Endpoint URL: https://{environmentVariable}.firstgiving.com/transaction/detail
Environment Variables: qa-api - QA Environment
  api - Production Environment
REST HTTP Method: GET
Authentication: JG_APPLICATIONKEY
JG_SECURITYTOKEN
URL Parameters: transactionId

 

Example Success Response:

HTTP Response: 200 OK

Relevant Header Values (applicable for all response types):

Jg-Execution-Time Time in milliseconds the transaction took to complete from when the original request arrived to when the response was sent by the FirstGiving server.
Jg-Environment Indicates which environment the request came from; possible values: 'staging', 'qa', 'production'.
Jg-Response-Signature Cryptographic signature to be used with the Verify endpoint.
X-Powered-By Indicates which FirstGiving server the transaction was processed on. Recommended to log and provide with any request for support.

Success Response Body:

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Success">
<transaction>
<transactionId>a-e8f8a121ce4ea1af1a8e5a</transactionId>
<currencyCode>USD</currencyCode>
<amount>11.0000</amount>
<billToFirstName>FirstName</billToFirstName>
<billToLastName>LastName</billToLastName>
<billToAddressLine1>123 Test St</billToAddressLine1>
<billToCity>TestCity</billToCity>
<billToZip>10001</billToZip>
<billToCountry>US</billToCountry>
<billToEmail>test.email@test.test</billToEmail>
<status>Awaiting Authorization</status>
<commissionFees>0.1600</commissionFees>
<ccFees>0.2800</ccFees>
<totalFees>0.4400</totalFees>
<netToOrganization>10.5600</netToOrganization>
<paymentId>0</paymentId>
<paymentStatus>UNPAID</paymentStatus>
<postingDate>1900-01-01T00:00:00</postingDate>
</transaction>
</firstGivingResponse>
</firstGivingDonationApi>

 

Possible Error Responses:

If the JG_APPLICATIONKEY and/or JG_SECURITYTOKEN are invalid:

HTTP Response: 401 Unauthorized

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="Bad JG_APPLICATIONKEY and JG_SECURITYTOKEN."/>
</firstGivingDonationApi>

If the JG_APPLICATIONKEY and JG_SECURITYTOKEN do not correspond to the same API Partner that processed the transaction (i.e. Key+Token and TransacitonID are valid, but the transaction was processed by another Key+Token pair):

HTTP 404 Not Found

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="Resource not found." verboseErrorMessage="A request having method 'GET' was made from IP '127.0.0.1' to request URI '/transaction/detail?transactionId=a-e8f8a121ce4ea1af1a8e5a', but this was not able to be resolved to a Donation REST API resource." />
</firstGivingDonationApi>

If the transactionId value is not valid:

HTTP 400 Bad Request

<?xml version="1.0" encoding="utf-8"?>
<firstGivingDonationApi xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<firstGivingResponse acknowledgement="Failed" friendlyErrorMessage="An error occurred. Please check your input and try again." verboseErrorMessage="The requested transaction was not found."/>
</firstGivingDonationApi>

 

API Call Verification

/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

 

Javascript Donation SDK

This documentation is located here:

https://app.firstgiving.com/DonationSdk

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 Verfiy endpoint below.

Verify
You can verify the entire data payload of a notification given it’s 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.

Additional 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.

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 log into your API Partner Reporting account and provide the system 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.
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. Additionally, please keep in mind that when testing the Hosted Payment Page in the sandbox environment, the sandbox charity UUIDs need to be used, as well. 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.

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.
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
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
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

Nonprofit Search Plugin

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

gearAdvanced Features
loader
Within miles of zip
Error
 

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>