One of the most important interactions at Kiva is finding and choosing loans. We figured one way to make API-based apps more powerful and useful was to allow them to assemble baskets for checkout at Kiva. In a way, this gives you complete flexibility over the shopping process, creating entirely new interactions for browsing and saving loans. You can even help the user choose a donation amount too, saving a step in the checkout process.
Imagine a mobile application that allowed a user to quickly browse and sort through all the loans currently available at Kiva. Whenever the user found a loan he liked, he might tap a button that saved that loan for purchase later. After quickly collecting 5 loans he liked (all without loading a single web page), he could click a button to be transferred to www.kiva.org with all 5 loans in his basket and various amounts to lend to each. Because he saved a preferred donation percentage in the app, the mobile app already added a 10% donation to his basket as well. All this is possible through a POST request to this URI:
To set the contents of a basket, you need only the ID of the loan or loans you want to set and the amount, in dollars, to lend. This information is passed in a simple JSON structure assigned to the loans
variable in the POST body of your request:
Above you see an ordered array of associate arrays, each representing a loan purchase request composed of id
and amount
. Simple. To add a donation, just supply the decimal amount to the donation
value in the POST body. If your application is a web page, the easiest way to do this to pass each variable as an INPUT
element in an HTML form:
There are, of course, some limitations:
You can have a link appear back to your app on the Thanks page, after the checkout is complete. When posting to the basket also set:
Note that the domain of the callback must match the domain of your app. Currently this is an experimental feature.
The result will look like this: