Transactions - Data for Education
15153
page-template-default,page,page-id-15153,page-parent,page-child,parent-pageid-15119,ajax_fade,page_not_loaded,,side_area_uncovered_from_content,qode-theme-ver-10.0,wpb-js-composer js-comp-ver-4.12,vc_responsive

Transactions

Overview

Our JSON API can be used to make project donations and purchase gift cards!

You can issue DonorsChoose.org gift cards to your customers which they can then use to support classroom projects at DonorsChoose.org. 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.org’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.org 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.org 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.org “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=DONORSCHOOSE

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:

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: https://apiqasecure.donorschoose.org/common/json_api.html?APIKey=DONORSCHOOSE (different sub-domain than the production API request URL above)

Using the APIkey: “DONORSCHOOSE”
And the apipassword: “helpClassrooms!”

We ask that you make your test transactions in very small denominations (eg. <=$5) since at present we need to manually replenish the credits in the test account…which we’d like to do infrequently, if possible.  🙂

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.