This API action allows you to donate to a proposal. We're unable to make this option available to everyone. So if you're interested in using API project donations, get in touch with us so we can discuss how best to meet your needs.
Protecting Transactions (reminder)
To ensure the integrity and security of all transactions, we require that...
- all transactions must be authenticated with an apipassword which we will issue to you in addition to the regular APIKey.
- all donation transactions must supply a non-reusable donation token which is obtained first in a separate request (see below for details).
- all requests must be sent as a POST (rather than a GET) to prevent any servers from logging the apipassword.
- all requests be made via HTTPS to our secure API host, see below... (instead of https://api.donorschoose.org/ as with all non-transactional API traffic)
- all transactions must include a token to prevent duplicate submissions
Secure API Request URL (reminder)
All requests should be POSTed to the following URL: https://apisecure.donorschoose.org/common/json_api.html
Shared Parameters (reminder)
These parameters are shared by all transactional API requests. All parameters except APIKey should be sent in the POST body:
| APIKey (required) | Your unique API Key |
| apipassword (required) | Indicate in your API key request that you need to do transactions. |
| action (required) | Must be "donate" for this step. |
| token (required) | The token you acquired with a previous "token" action |
| callback (optional) | If you wish to wrap your response in a callback function, include the name here. |
Steps to Make a Donation
Making donations through our API requires two steps:
1) Sending a request to obtain a token for the donation. This code will be unique and can only be used once for a donation.
2) Sending a request to make the donation. This request will include the token along with other required parameters.
Obtaining a Transaction Token
You must specify the following parameters:
| action (required) | Must be set to "token" for this step. |
Making a Donation
You must provide the token, proposalId, donation amount, and some donor information.
For the donor, only email address is required. You can supply first name and last name if you wish to update them. We strongly encourage you to also supply their city and state as the classrooms love knowing where their supporters reside! The full address of the donor is totally optional, but we encourage you to invite your donors to supply it for donations of >=$100 or else they won't receive the awesome hand-written thank-you notes from the classroom. ?
If the transaction succeeds, we'll debit the donation amount from the account associated with your APIKey.
If you specify a donation amount larger than the amount remaining in the proposal, the donation will fail. This can happen if the project receives a donation from another generous donor in the time between when you last retrieved the project's amount remaining and the moment at which you make the donation. If this happens, you can examine the response (see below) to determine the project's amount remaining and then try again with an adjusted donation amount.
| proposalId (required) | ID of the project to receive the donation. (Typically a 6-digit number.) |
| amount (required) | Dollar amount to donate to the proposal. (Must be a whole number (no cents) >=$1 unless you're making the project's "completing" donation, in which case you must specify the exact amount remaining for the project.) |
| email (required) | Email address of the person to whom the donation should be credited. (This must be a known-good email address so that we can send the donor a receipt for tax purposes and later the thank-you assets from the classroom: the thank-you note, impact letter, and photos.) |
| first (required for first-time donors only) |
First name of person to whom the donation should be credited. (This field should be accurate for tax purposes. On our site, only the salutation will be revealed publicly.) |
| last (required for first-time donors only) |
Last name of person to whom the donation should be credited. (This field should be accurate for tax purposes. On our site, only the salutation will be revealed publicly) |
| salutation (required for first-time donors only) |
How the donor wants to be acknowledged on our site, eg. Timothy, The Richards Family. (We recommend defaulting this value to simply First Last and then inviting the donor to alter it if they want.) |
| address1 (optional) | First line of street address of person to whom the donation should be credited. (Required if the donor wants to receive the awesome hand-written thank-you notes from the classroom they supported!) |
| address2 (optional) | Second line of street address of person to whom the donation should be credited. (Required if the donor wants to receive the awesome hand-written thank-you notes from the classroom they supported!) |
| city (optional) | City of person to whom the donation should be credited. (Strongly encouraged so the classroom can know where their supporters reside!) |
| state (optional) | State of person to whom the donation should be credited. (Strongly encouraged so the classroom can know where their supporters reside!) |
| zip (optional) | 5-digit zip code of person to whom the donation should be credited. (Required if the donor wants to receive the awesome hand-written thank-you notes from the classroom they supported!) |
| requestThankYouNotes (optional) | Set this to 'true' for the donor and honoree to receive thank notes from the classroom. When this is true, the donor and honoree's address parameters are required. |
Honoree parameters
You can make donations in honor of someone, and he or she will receive a notification about the donation and, if requested, thank-you notes from the students for eligible donations.
| honoreeEmail (optional for donation; required for honoree) | The honoree's email address. |
| honoreeFirst (optional for donation; required for honoree) | The honoree's email address, as it will appear on the site for the donation. |
| honoreeLast (optional) | The honoree's last name. Required for the honoree to receive thank-notes from the classroom. |
| honoreeAddress1 (optional) | First line of the honoree's address. Required for the honoree to receive thank-notes from the classroom. |
| honoreeAddress2 (optional) | Second line of the honoree's address. |
| honoreeCity (optional) | The honoree's city. Required for the honoree to receive thank-notes from the classroom. |
| honoreeState (optional) | The honoree's state. Required for the honoree to receive thank-notes from the classroom. |
| honoreeZip (optional) | The honoree's zip code. Required for the honoree to receive thank-notes from the classroom. |
Test parameters
You can also supply the following test parameters, which could be useful for your development.
| testDelaySeconds (optional) | Set to force a delayed response from the server. You can use this to test handling requests that take longer than your timeout setting. |
| testFail (optional) | Set to "true" and the server will return a service unavailable response (503). This would likely be used with the testDelaySeconds parameter. |
Donation Response
If successful, the response includes...
- a unique "donation ID" you can use for your reporting and your donor can use for any followup inquiries with our staff.
- an URL which you can use to show the updated project reflecting this most recent donation.
- the project's amount remaining, which can be 0 if the project has been completed.
| statusCode | Numeric status code, one of:0 ? "success" 1 ? "insufficient balance": 2 ? "donation amount larger than remaining ? not allowed": 3 ? "invalid proposal id": 4 ? "internal error: giving cart add error": 5 ? "internal error: invalid cart": 6 ? "invalid contact/payment info": 7 ? "project was fully-funded or expired" 10 ? "internal error: please retry": 20 ? "duplicate transaction code" 30 = "invalid honoree information" |
| statusDescription | String description of error, see above for the strings (do not rely on these strings staying the same, if you want to test for a specific error, use the numeric codes which will not change) |
| donationId | A unique "donation ID" for reporting and any customer service inquiries. |
| remainingProposalAmount | The project's amount remaining, which can be 0 if the project has been completed. |
| proposalURL | An URL which you can use to show the updated project reflecting this most recent donation. |
In addition to the above, on a donation receipt will be emailed to the donor for tax purposes.
Donation Request Example
POST /common/json_api.html?APIKey=[YOUR_API_KEY] HTTP/1.1
POST body:
apipassword=sampleapipassword&action=donate&token=ABCD-12345-XYXYZ-12345&proposalId=17246&amount=125.00&email=donoremail@donor.com&first=Jane&last=Smith&city=Denver&state=CO
Donation Response Example
Here's an example response:
{"statusCode":"0?,
"statusDescription":"success",
"donationId":"142321?,
"remainingProposalAmount":"54.50?,
"proposalURL":"https://www.donorschoose.org/donors/proposal.html?id=259649&utm_source=api&utm_medium=donate&utm_content=bodylink&utm_campaign=DONORSCHOOSE&cacheBust=812476172438123771284183?,
}
Communication
You should communicate to the end-user that you will be sharing their email address with us so that they can hear back from the classroom directly. We don't want your end-users to be surprised to hear from us.
If the end-user didn't hand-pick the project themselves, you're encouraged to tell them the project they supported and link to it. This info is in the successful transaction API response.
When a live API transaction succeeds, you'll get an email from us detailing the amount of the gift code and your remaining account balance. Also, your end-user will get an email from us thanking them for their donation and linking to the project they supported.
Donation Functional Limitations
These capabilities of the DonorsChoose front-end are not currently available via the API:
- You can only donate to one project at a time.
- You cannot put multiple projects in a "cart."
- You can donate to a project that's on a Giving Page or donate to a project that you want added to a Giving Page.
- You cannot donate to a Giving Page and have the API automatically pick the receiving project.
- You cannot specify that a project donation has been made in memoriam.
- You cannot opt-out of the 15% optional donation to support the work DonorsChoose does to engage teachers, acquire donors, and generally run our operation.
- You cannot create a new account, ie. set a password for the donor so that they can access their donation history and use other account-based features.
- The donor can create an account at any time in the future by accessing our front-end and using the email address associated with their API donation.