Overview
Our JSON API can be used to make project donations and purchase gift cards!
You can issue DonorsChoose gift cards to your customers which they can then use to support classroom projects at DonorsChoose. Since the API will enable you to issue a gift card to one of your customers in the denomination of your choosing and in the simple form of an 10-digit redemption code, you can use them for dynamically generate and issue "philanthropic customer rewards" of any size.
Or you could show your site visitors classroom classroom project listings and then process the donation to a project behind-the-scenes without having to route your site visitor to DonorsChoose's front-end!
In all scenarios, our initial approach to transactions is to handle the actual transferring of funds between partners like you and DonorsChoose outside of our API. You can't pass in an end-user's actual billing info (credit card, PayPal, Amazon Payments, Google Wallet or DonorsChoose gift card) into our API and have us charge them directly. Nor can you send us the funds electronically (ACH, etc) at the moment of the transaction.
Instead, you must purchase DonorsChoose "account credits" via our front-end and then your API transactions will draw-down on that credit balance. Alternately, for high-volume partners, we can arrange an off-line billing arrangement with you, eg. whereby you sign a contract around the payment terms and then we invoice you regularly. If you are charging donors for their donations, you must do so directly and you will own the billing relationship with them.
If you are interested in using our API to make project donations or purchase, get in touch with us so we can review your scenario and provision your API key.
Protecting Transactions
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 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
All requests should be POSTed to the following URL:
https://apisecure.donorschoose.org/common/json_api.html?APIKey=[YOUR_API_KEY]
Unlike the read-only aspects of our API, these interactions are via HTTPS and use a different sub-domain.
Shared Parameters
These parameters are shared by all transactional API requests. All parameters except APIKey should be sent in the POST body in application/x-www-form-urlencoded format:
| 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) | One of 'token', 'donate', or 'giftcode' depending on whether you're requesting a token, making Project donations, or issuing Gift codes. |
| token (required) | The token you acquired with a previous "token" action |
Request Details
Testing
Request URL & credentials
You can submit test transactions...
To this request URL (our sandbox): https://apiqasecure.donorschoose.org/common/json_api.html?APIKey=[YOUR_API_KEY] (different sub-domain than the production API request URL above)
Contact us about filling your account in the sandbox with play money.
Sandbox availability & volume
These requests go against the same testing environment used by our staff so it's unfortunately not uncommon for it to be temporarily offline during rebuilds or accidental outages. We're sorry if the instability of this environment gets in the way of your testing! If you must have this test environment available during a specific time window, get in touch with us and we'll try our best to accommodate.
Also, since this is a shared testing environment that isn't resourced as robustly as our production environment, we ask that for now you avoid sending >1 transactional request every 2 seconds.
Verifying test transactions
To quickly verify that a test gift code purchase made via the API has succeed, we recommend visiting http: (slash)(slash) qa {dot} donorschoose (dot) org (slash) redeem and confirming that you can use the gift code to donate to a classroom project.
To quickly verify that a test project donation made via the API has succeeded, we recommend visiting the proposalURL supplied in the response and confirming that the test donation appears in the reverse-chronological list of project updates.