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 parameters 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
http://api.donorschoose.org/ as with all non-transactional API traffic)
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:
APIKey (required)
|
Request a unique API key. |
| apipassword (required) |
Indicate in your API key request that you need to do transactions.
|
| callback (optional) |
If you wish to wrap your response in a callback function, include the name here.
|
| action (required) |
Should be 'donate' for this type of transaction.
|
Donation Parameters
You must specify the proposalId, donation amount, and some donor information.
For the donor information, only name and email address are required. 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.)
|
salutation (optional)
|
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.)
|
first (required)
|
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)
|
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)
|
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!)
|
Donation ResponseIf 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":
not enough money left in account
2 - "donation amount larger than remaining - not allowed":
donation amount is greater than amount left in proposal
3 - "invalid proposal id":
proposal id either nonexistent or not taking donations
4 - "internal error: giving cart add error":
internal error, should not occur, if it does, please report to us
5 - "internal error: invalid cart":
internal error, should not occur, if it does, please report to us
6 - "invalid contact/payment info":
invalid contact/payment information supplied, such as invalid email address format
10 - "internal error: please retry":
an internal database error occurred, retrying the same request should work
|
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 ExamplePOST /common/json_api.html HTTP/1.1 ... APIKey=SAMPLEAPIKEY&apipassword=sampleapipassword&action=donate&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":"http://www.donorschoose.org/donors/proposal.html?id=259649&utm_source=api&utm_medium=donate&utm_content=bodylink&utm_campaign=DONORSCHOOSE&cacheBust=812476172438123771284183",
}
Donation Functional LimitationsThese capabilities of the DonorsChoose.org 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 someone else's honor or in memoriam.
- You
cannot opt-out of the 15% "optional donation" to support the work
DonorsChoose.org 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.
|
|
