Linking Back to Kiva

Populating Baskets

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't reserve loans. On Kiva, loans are reserved for the user as soon as they go into the basket. Using basket modification, loans are only reserved once the user arrives at the Kiva website. This could cause a problem if the user takes too long between finding a loan on Kiva going to basket checkout. A way to mitigate confusion would be to verify the user's choices are still available before transferring him to Kiva, giving an option to modify the choices before moving on to checkout. If the loans requested are not available, we'll put as much of the request amount in the basket as is available.
• You can only set, not get or add to, the basket. Baskets are associated with sessions in a browser. If you open a new browser window, it could create a new session with the basket contents. If your app simply loads the Kiva site in the same browser session, the current contents of the basket (if any) will be overwritten with the new contents. This is actually a feature as it allows applications predictable control over the basket contents while protecting the privacy of the user.

Returning to your app

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: