Flattr API

All events are expected to be dispatched on the Document object on any page on flattr.com.

Identification

The extension should indicate that it is installed by using sessionStorage to set the key to "extension" and the value to the extension's version string.

Furthermore, the extension should dispatch a "flattr-installed" event when its content script gets loaded and a "flattr-uninstalled" event when its content script gets unloaded.

Authentication

Initiated by webpage

1. Webpage starts Handshake
2. Extension dispatches "flattr-authenticated" event
   • boolean authenticated

Initiated by extension

Manual

1. Extension opens webpage in new tab when user clicks the "Sign in" button
2. Webpage starts Handshake
3. Extension closes tab

Automatic

1. Extension attempts to submit flattrs
2. Server responds with status 401 Unauthorized
3. Extension removes stored token

Handshake

1. Webpage dispatches "flattr-trigger" event
   • string action ("authentication")
2. Extension dispatches "flattr-authenticate" event
   • string build – This is the build ID.
   • string id – This is the extension ID.
   • string version – This is the extension version.
3. Webpage dispatches "flattr-token" event
   • string accessToken
   • Subscription subscription
4. Extension stores the token and updates the subscription accordingly

Subscription Change

Initiated by webpage

1. Webpage dispatches "flattr-subscription" event
   • Subscription subscription
2. Extension updates the subscription accordingly

Initiated by extension

1. Extension attempts to submit Flattrs
2. Server responds with status 402 Payment Required
3. Extension deactivates the currently active subscription

Subscription

• boolean active

Flattr Submission

The extension should submit flattrs as soon as it determines which URL to flattr and it should retry the submission in the case of any of the following network errors:

• 408 Request Timeout
• 409 Conflict
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Time-out
• 525 SSL Handshake Failed
• 599 Network Connection Timeout Error

Request

API Endpoint: https://api.flattr.com/rest/v2/flattr/bulk

Method: POST

Headers:

Content-Type: application/json
Authorization: Bearer <token>

Body:

[
  {
    "url": "<url>"
  },
  ...
]