The following is a WIP. The final specification for V1 will likely contain changes.

Overview

Recurr is designed such that it operates upon similar principles as an RSS feed.

A services provides a unique HTTP endpoint to each user of the service. For example:

https://your-service.com/feed/9586f67464963a6ed4c6d6b7fababe23

This endpoint then returns a JSON payload that contains basic service details and optionally (depending upon the type of service):

Bill Items (For Phone, Internet, Utilities, Service Subscriptions, etc)
Balance Items (For Prepaid Services, Cryptocurrency Exchanges, etc)
Receipt Items (For Payment History)

The service can then present a QR Code (or link) to the user to scan into their Recurr App either online or on their bill (if it's a utility service).

After a user scans a feed, the Recurr App will automatically poll this endpoint for updates at regular intervals or upon app focus.

As Item Actions are defined as simple URL links, it should be possible to easily integrate Recurr with existing services and almost all modern payment gateways/methods.

Feed Payload

The JSON payload given by the endpoint has the following format:

{
  "type": "recurr", // (required) Must be "recurr"
  "version": "1.0", // (required) Version number of protocol
  "title": "Your Service", // (required) Name of your service
  "caption": "john.smith@email.com", // (required) Caption for service (usually the account name)
  "icon": "https://recurr.app/examples/icons/recurr.svg", // (required) Icon for service
  "bills": { }, // (optional) List of invoices/bills
  "balances": { }, // (optional) List of balances (e.g. for prepaid services)
  "receipts": { }, // (optional) List of receipts
  "actions": [ ] // (optional) Service-wide actions (e.g. "My Account" link)
  "mode": { } // (optional) The "merge" mode to use for bills, balances and receipts (update vs set)
}

Bills, balances and receipts are formatted as Key=>Value pairs (as opposed to arrays). This is necessary so that updates and notifications work correctly.

Examples and further details of each are given below.

Bill Items

Bills are optional and can be used to notify the user of upcoming/overdue bill items. For example:

Internet/Phone Bills
Utility Bills
Rental Properties
Service Subscriptions

{
  // ...
  "bills":{
    "605f0fd4a30c3c0036c19a70":{
      "title":"March 2021",
      "amount":49.99,
      "currency":"AUD",
      "due":"2021-04-02T10:58:28.661Z",
      "actions":[
        {
          "title":"Pay using Stripe",
          "icon":"http://recurr.app/icons/action-stripe.png",
          "url":"http://recurr.app/examples/stripe/605f0fd4a30c3c0036c19a70"
        },
        {
          "title":"Pay using Bitcoin Cash",
          "icon":"http://recurr.app/icons/action-bch.svg",
          "url":"http://recurr.app/examples/bitcoin-cash/605f0fd4a30c3c0036c19a70"
        }
      ]
    }
  }
}

Balance Items

Balacnce Items are optional and generally used by prepaid services or other services where the user has an account with a balance. For example:

Prepaid Phone/Internet Accounts
Cryptocurrency Exchanges

{
  // ...
  "balances":{
    "605f1068a30c3c0036c19aea":{
      "title":"March 2021",
      "amount":2.99,
      "low":10,
      "currency":"USD",
      "actions":[
        {
          "title":"Top up using Stripe",
          "icon":"http://recurr.app/icons/action-stripe.png",
          "url":"http://recurr.app/examples/stripe/605f1068a30c3c0036c19aea"
        },
        {
          "title":"Top up using Bitcoin Cash",
          "icon":"http://recurr.app/icons/action-bch.svg",
          "url":"http://recurr.app/examples/bitcoin-cash/605f1068a30c3c0036c19aea"
        }
      ]
    }
  }
}

Receipt Items

Receipts are optional and can be used to show the user their payment history.

{
  // ...
  "receipts":{
    "605f0fd4a30c3c0036c19a71":{
      "title":"March 2021",
      "amount":21.46,
      "currency":"AUD",
      "due":"2021-03-27T10:58:28.661Z",
      "paid":"2021-03-26T10:58:28.661Z",
      "actions":[
        {
          "title":"View Receipt",
          "icon":"http://recurr.app.localhost/icons/receipt.svg",
          "url":"http://recurr.app.localhost/examples/receipt.pdf"
        }
      ]
    }
  }
}

Service Actions

Service Actions are optional and can be used to offer convenient service-specific shortcuts to the user. For example:

Offering "Manage Account" Link
Offering "Contact Us" Link

{
  // ...
  "actions": [
    {
      "title": "My Account",
      "url": "https://your-service.com/login"
    },
    {
      "title": "Contact Us",
      "url": "tel:1800123123"
    }
  ]
}

Mode

When refreshing a feed, Recurr will attach a "delta" query parameter containing a timestamp of the last successful refresh.

This can be leveraged by the service to save bandwidth by only sending updated information for a given item type.

By default, mode is "set" for all item types meaning that the entire object will be overwritten. However, as receipts can get quite large and is typically only appended to, it is recommended to use "update" for this item type.

{
  // ...
  "mode": {
    "bills": "set",
    "balances": "set",
    "receipts": "update"
  }
}