simple social payments for great people, causes & content
Tipjoy's API is currently in development. Here are some quick tools you can use now though
-->Tipjoy API & tools
This page is evolving. There are other APIs and tools available which we haven't yet documented. Let us know if you'd like to see more information about anything on Tipjoy. Also let us know if you see anything missing. get in touch
For an open source example of use of our API, check out tatatweet. GitHub repository here: http://bit.ly/git_tatatweet
Click here for a tutorial on using the API to power Twitter paymentsContents
Creating a Tipjoy account using Twitter credentials
Checking if a Tipjoy account exists
Notifying Tipjoy of a Twitter Payment
Extracting batch transaction data, including Twitter Payments
The parameters used in custom Tipjoy widgets
Authentication for API calls
Some of these calls are just open data feeds, with no authentication required. We think making data more open makes it more valuable. Please set a user-agent if you plan heavy use of open feeds.
A user can set their Tipjoy transactions to be private, which requires authentication to view. We're against username/password authorization, and we think it's a bad user experience to give users keys to cut and paste.
We think OAuth is the best solution, and will hold off allowing really powerful tools (like a money moving API), until we support OAuth. This should be available soon, but ping us to push for it faster.
That said, we're making tools for Twitter API developers for Twitter Payments. So, for now, we allow authorization for some calls with a Twitter username & password or with a sign OAuth request to the verify_credentials Twitter REST API endpoint.
OAuth access to a user's account is not transferable between Twitter OAuth consumers. So for a Twitter app which uses OAuth to authorize a Tipjoy API call, they need to set the twitter_oauth_header parameter with a properly escaped Authorization string generated by signing an OAuth request to verify_credentials.
You need to create a new twitter_oauth_header for each attempt to access our API, because it contains a nonce that precludes reuse.
Here is an example of the header, and then again properly escaped.
Here is a bit of python code which shows how to take an OAuth Token and OAuth Token Secret to get this header. It makes use of this OAuth library.
top
API for creating a Tipjoy account with Twitter Credentials
Our Twitter payments using Tipjoy make it so that Twitter now has a payments API. Twitter based services can automatically create Tipjoy accounts with Twitter credentials using this API. Set the parameters below and HTTP POST to:
Parameters
twitter_username - the username on twitter (required)
twitter_password - the password on twitter (this or twitter_oauth_header is required)
twitter_oauth_header - the Twitter OAuth authorization header (this or twitter_password is required)
format - the format of the reply. Options in include nvp for name value pairs and json for JSON (optional, json default)
autoTweetTips - account setting for new users. Values accepted are "true" or "false". "true" means payments will be tweeted to the users twitter stream, except for payments initiated on twitter (optional, True default)
Response
result - "success" or "failure"
reason - if the result is "failure", the reason might be "must POST", "missing twitterUsername", "missing twitterPassword", or "invalid twitter username or password"
username - if the result is "success", this is the Tipjoy account username. It might not be the same as the given twitterUsername due to an existing user with that name
userId - if the result is "success", this is the Tipjoy account user id. Because usernames can change, this is a good way to refer to the account.
Examples
Failure, JSON return
POST:
response:
Success, name/value pair return
POST:
response:
Sample python code
top
Checking if a Tipjoy account exists
Before creating an account, you can check if it already exists
Parameters
twitter_username - the username on Twitter
username - the username on Tipjoy
email - the email address of the user on Tipjoy. Note that it is easy to modify an email address to make it not match this query. For example 'ivan.kirigin+SomeSite@gmail.com' won't match 'ivan.kirigin@gmail.com'. Many users modify their emails like this when signing up for other services
Response
result - 'success' or 'failure'. Failure doesn't mean the account doesn't exist, but that the request was malformed. Success doesn't mean the account exists
reason - if 'result' is 'failure', gives the reason, either 'missing username, email, or twitter_username' or 'must HTTP GET'
exists - True or False
user information - information about the user account if it exists, matching this format.
top
Notifying Tipjoy of a Twitter Payment
The Tipjoy API can be used via Twitter applications that have OAuth-ed users. You can create a signed request to authenticate for our API, but that doesn't enable Tipjoy to post a tweet on the user's behalf.
So in place of posting a twitter payment directly, API users can post the tweet directly to Twitter, and notify Tipjoy using this call. To get the public transaction information, just http POST to:
Parameters
tweet_id - the Twitter ID of the tweet containing the payment
Response
result - "success" or "failure"
reason - if the result is "failure", the reason might be "must POST", "missing tweet_id", etc.
transaction data - following this format.
top
Initiating a Twitter Payment
The Tipjoy integration into Twitter allows for payments to be initiated via status updates. This makes it easy to do payments in any twitter client.
To perform an action in response to a payment in real time, it is more efficient to tweet through Tipjoy than to wait for Tipjoy to pick up the tweet.
The user must have a positive balance greater than the transaction amount, if the amount is larger than $500.
Note that this call is unavailable via Twitter OAuth access, as it requires posting to Twitter. Rather than mirroring their API, just post a tweet, and tell us about it using this call.
Parameters
twitter_username - the username on twitter (required)
twitter_password - the password on twitter (required)
text - the text of the tweet (required). This must represent a payment tweet
currency - the currency code for the returned balance. To transact in other currencies, set the text param appropriately, e.g. use £ 1 in the tweet for GBP instead of $1. (optional, defaults to 'USD')
Response
result - 'success' or 'failure'
request - The call made
reason - if the result is 'failure', the reason might be 'must HTTP POST', 'missing twitter_username', 'missing twitter_password', 'invalid twitter_password', 'no such tipjoy user', 'missing text', 'missing target', 'missing amount', 'tweet failed'
transaction_ids - An array of integer transaction IDs. Typically will be of length 1. If the user had a positive balance, and the payment was greater than balance, there will be two transactions in Tipjoy, one paid and one unpaid.
isLoan - boolean, designating whether the transaction is fully paid
transactionTime - the time of the transaction
tweet_id - the ID of the tweet, from Twitter
amount - the full amount of the transaction, paid or otherwise, as a float
amount_paid - the paid amount of the transaction, as a float. If isLoan is true, this will be less than or equal to amount
balance - if the result is 'success', this is the Tipjoy user's balance, as a float.
currency - the currency code of the balance amount, default 'USD'.
top
Checking a User's balance
Users in Tipjoy can go into debt, and have negative balances. This call grabs their current balance. Authentication is via twitter credentials. Complete a GET request to:
Parameters
twitter_username - the username on twitter (required)
twitter_password - the password on twitter (this or twitter_oauth_header is required)
twitter_oauth_header - the Twitter OAuth authorization header (this or twitter_password is required)
currency - the code of the currency to reflect the balance, 'USD' or 'GBP' (optional, default 'USD'). Note that Tipjoy's accounting is based in USD, so the balance in other currencies could fluctuate with exchange rates without new transactions.
Response
result - 'success' or 'failure'
request - The call made, including GET parameters
reason - if the result is 'failure', the reason might be 'must HTTP GET', 'missing twitter_username', 'missing twitter_password', 'invalid twitter_password', or 'no such tipjoy user'
balance - if the result is 'success', this is the Tipjoy user's balance, as a float.
currency - the currency code of the balance amount, default 'USD'.
top
Create Login Link
Applications that use this API can automatically create users, post transactions, extract transaction data, and get a users balance. But what if the balance is negative? The application should send the user to PayPal to fill their Tipjoy account. If a user would like to change some settings, they need to sign in to their Tipjoy settings page. The way to accomplish this is to create a link for the user to use that will sign them in, and redirect them to the right page. Complete a POST request to:
Parameters
twitter_username - the username on twitter (required)
twitter_password - the password on twitter (this or twitter_oauth_header is required)
twitter_oauth_header - the Twitter OAuth authorization header (this or twitter_password is required)
url - the url on Tipjoy to redirect to upon sign in, e.g. 'settings' for editing the user's settings, or 'buymore' to be signed in presented with a form to pay. If not present, sends the user to http://tipjoy.com (optional)
Response
result - 'success' or 'failure'
request - The call made
reason - if the result is 'failure', the reason might be 'must HTTP POST', 'missing twitter_username', 'missing twitter_password', 'invalid twitter_password', or 'no such tipjoy user'
login_url - if the result is 'success', this url will sign in the user and redirect them to the url passed in, or just http://tipjoy.com/
top
Extracting batch transaction data, including Twitter Payments
Tipjoy transactions are by default public, and we think the social capital they represent is valuable. We're making it more valuable by being open with the data. This API is an initial implementation, with a data extraction tool that returns information about the transactions, the users behind them, and linked social network accounts like Twitter. The results are returned in JSON. The transaction might be unpaid, recorded as pledges. You can use this call to later test if an individual transaction has been paid. Set the parameters below and HTTP GET to:
Parameters
url - the URL that indexes the content (optional). This is the permalink for the content that tipjoy links. If not present from a transaction, the tipjoy profile page is used, i.e. tipjoy.com/u/username. To extract transactions sent to a particular Twitter user, use twitter.com/twitterUsername, e.g. transactions to @tipjoy.
rpp - requests per page, the max number of results to return
page - page of results, starting at page 1. For example, page 3 with an rpp 5 starts on result #11.
source_twitter_username - the twitter username of the Tipjoy user making the payments - an alternative to the url parameter
target_twitter_username - the twitter username receiving the funds.
since_id - shows only transactions after this transaction_id
tweetPaymentsOnly - True or False - set to True to only include transactions from Twitter Payments. (only for source_twitter_username)
withFriends - True or False - set to True to also include transactions from friends on Tipjoy. Following someone on Twitter makes them your Tipjoy friend. (only for source_twitter_username)
twitter_password - the password on Twitter for either the sourceTwitterUser account or the target_twitter_username. For sourceTwitterUser it is required to display identifying information of Tipjoy users with private transactions. For target_twitter_username, in addition to identifying information of Tipjoy users with private transactions, the payer contact information (e.g. email address) will be included.
twitter_oauth_header - acts like twitter_password, but for Twitter OAuth access
Response
result - "success" or "failure"
reason - if the result is "failure", the reason might be "must POST", "missing source_twitter_username", "missing twitter_password", or "invalid twitter username or password"
count - the number of transactions returned
transactions - a list of transactions, each with the same set of transaction data, following this format.
Example:
top
Show single transaction data
This shows data from individual transactions. Payments in Tipjoy are flexible in that they can be pledges to pay later. This means you might need to track an individual transaction to detect if it has been paid. We're also considering adding a callback to your settings which would perform a POST from Tipjoy when a transaction was pledged, paid, or canceled. If you need that functionality, let us know.
Set the id parameter and HTTP GET to:
Parameters
id - the id of the transaction, probably found using the batch data extraction format, and recording the transaction_id
Response
result - "success" or "failure"
reason - if the result is "failure", the reason might be "must POST", "missing twitterUsername", "missing twitterPassword", or "invalid twitter username or password"
transaction data - following this format.
Example:
top
Transaction data format
Transactions that are listed in the batch extraction or individual calls each have the following format
transaction_id - the id of the transction. You can store this to, for example, check if a payment has gone from pledged to paid, using this call.
username - the Tipjoy username of the payer. A user can change their username. If transactions are private from this user, this will list 'anonymous'
userid - the Tipjoy user id of the payer. This does not change.
private - a boolean, if true will hide donor information.
date_joined - date and time the Tipjoy user joined Tipjoy
isLoan - a boolean, if true this transaction is pledged but not paid.
verified - a boolean, if true this user has filled their Tipjoy account before.
permalink - a url of the content.
time - the transactions time
prettyTime - a short English description of the relative transaction time, e.g. '2 hours ago'.
amount - the dollar transaction amount
twitter_username - the Twitter username of the Tipjoy user, only present if they have a Twitter account linked to their Tipjoy account.
twitter_user_id - the Twitter user id of the Tipjoy user, only present if they have a Twitter account linked to their Tipjoy account.
profile_image_url - the Twitter profile image of the Tipjoy user. This can be lagged if the user has updated their profile picture.
tweet_id - the tweet id if this transaction was a Twitter Payment.
tweet_message - the text of the tweet of the Twitter Payment
tweet_message_html - the text of the tweet of the Twitter Payment, with links and @usernames rendered in HTML.
top
User account data format
User accounts returned as part of transaction information will include the following data
username - the Tipjoy username of the payer. A user can change their username.
user_id - the Tipjoy user id of the payer. This does not change.
date_joined - date and time the Tipjoy user joined Tipjoy
is_private - a boolean, if true the user's transaction information is private
verified - a boolean, if true this user has filled their Tipjoy account before.
twitter_username - the Twitter username of the Tipjoy user, only present if they have a Twitter account linked to their Tipjoy account.
twitter_user_id - the Twitter user id of the Tipjoy user.
profile_image_url - the Twitter profile image of the Tipjoy user. This might slightly lag to reflect when a user changes their profile image. Blame a poor naming convention from twitter.
top
Payment Tweet Pattern Format
To initiate a payment over twitter, the tweets needs to contain a payment keyword, a transaction amount, and a recipient for the transaction. We tokenize the text, splitting pieces on whitespace. For example, "hi there, john" would make 3 tokens: ['hi', 'there,', 'john']
Keywords
The basic keywords are 'rtip', 'p', 'give', 'tip', 'pay', 'tipjoy'. Only 'rtip', 'p', and 'give' can occur anywhere in the tweet. The rest must be within the first 3 tokens.
Currencies
Currently, we transact in USD and GBP. For USD, the amount must be represented as a positive float value beginning with $ or ending with ¢. For GBP, the amount must begin with £ or end with 'p' for pence. Tipjoy's accounting is in USD, so any other currency is immediately converted to USD to debit the correct amount. We will add filters soon to receive other currencies. Eventually, we'll represent other currencies explicitly on our back end.
Targets
The target can be an twitter username beginning with '@', a url beginning with 'http:' (google.com doesn't work), or an email address.
Ordering
Upon finding a payment keyword, we search the nearby tokens for an amount and target. We start scanning right 2 tokens from left to right (or 3 if we find 'to' or 'for'), then scan left 2 tokens from right to left. To illustrate this, if we have the string 'X1 X2 p for X3 X4', the tokens would be scanned in this order: ['for', 'X3', 'X4', 'X2', 'X1']. Again, 'rtip', 'p', and 'give' can be used anywhere within a tweet, but 'tip', 'pay', and 'tipjoy' must be within the first 3 tokens.
top
The parameters used in custom Tipjoy widgets
Overview
This is a description of parameters available to our customizable widgets. Tipjoy widgets are iframes, at times loaded via javascript. This custom widget is different than other widgets because the visible widget is actually written to the DOM and is not an iFrame. The iframe is loaded in a lightbox when a user clicks the "give" button. This means that 3rd party CSS can be used to customize everything outside the lightbox, and additional parameters can be used to customize the text in the iframe. Example CSS can be found here.
The widget is loaded by including the following code, with the parameters described below filled in. This code is a div to store the widget and a piece of javascript to load the widget. Place the div anywhere, but we recommend putting the javascript at the very end of your page body.
Parameters - you MUST designate AT LEAST one of these two paramaters
username - the recipient of the funds. If you do not define a target user who should receive the funds then you MUST define a url. If a url is designated but a user is not, a placeholder account is used.
url - the permalink for the content. If you do not define a URL which should receive the funds then you MUST define a username. If you designate only a username and not a url, transactions will be directed to the target user, with their tipjoy profile page url as the permalink. We recommend including a url in order to better describe the reason for the transaction. If you do not include a url, your content will not be displayed in any of our public lists such as 'recent' or 'popular'.
Optional parameters
message - the title text to prompt someone to donate, used above the tipjoy button on your page and in the lightbox.
amount - a floating point US dollar amount that acts as a default for the transaction, though the giver can customize the value. People don't change defaults often, so try to set the default amount appropriately for the value of the content. The amount must be greater than zero.
tipperMessageTitle - when your readers tip, you can choose to ask them to leave you a short message. You can customize the text of the message question. For instance, a blog about coffee can ask "what's your favorite drink?" Twitter would ask "what are you doing?"
Additional parameters for Platforms
Platform accounts make it easy for user-generated content sites to automatically create accounts for all their users. They can also split the earnings with their content creators. Apply to request a platform account here.
platform - the platform username. The transaction will be split between the target user and the platform as you have designated in your Platform account.
user, domain - designates an email address of the person that will be the recipient of the transaction. Since you are a platform you can use this instead of username. Email addresses that are not in our system have accounts created for them. user is the name on the email domain. For example: ivan.kirigin@gmail.com would be user=ivan.kirigin&domain=gmail.com
For Platform accounts: a word on user account creation - automatic vs. opt-in
Platforms have the ability to create accounts from email addresses by parameterizing buttons appropriately or making a call from their server side. The email address is available to anyone loading the widget, but is obfuscated slightly by the user/domain pairing, so is unlikely to be harvested by spammers. More pressing is the privacy issue. Passing an email address to Tipjoy might violate your terms of service. If so, loading the widget should be opt-in.
Luckily, widgets can be loaded without a target user designated. The url param can be used to accumulate transactions. Then the new user could be notified of money waiting, and allowed to opt-in. Loading the widget with that url with a user designated will initiate a confirmation process in Tipjoy that will send the accumulated funds to the new Tipjoy account. Alternatively, the user could just be presented with a dialogue box to opt-in right when joining.
The simplest solution is for you to create Tipjoy accounts for all your users automatically. This has the added benefit of the network effect: the more users are hooked into Tipjoy on your platform, the more likely it is that your users will give and earn money.