FirstGiving Donations 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

Sandbox Donations API Server

Test Card Data for Sandbox

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:

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

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.

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…


API Authentication
In order to submit requests against our API, you must first signup as a 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


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

POST Response Values



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

POST Response Values



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.

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 a message that you have received actually originated from FirstGiving’s API.
GET Input Values

GET Response Values

GET Response Values



Transaction Lookup

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


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

More Details

Recurring Donations
irstGiving 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 then our system would formulate a request and query string like 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.

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:


FrontStream Holdings LLC is a registered ISO of Elavon, Inc. Georgia, Chase Paymentech Solutions, LLC, First National Bank of Omaha, Omaha, NE, BMO Harris Bank, N.A., Chicago, IL, Deutsche Bank, USA, New York, NY and Wells Fargo Bank, N.A., Walnut Creek, CA.