Back to top

Payback API

Payback API is a service to track and optimize debts between a group of friends.

Authentication

Currently the Payback API does not provide authenticated access. Authentication will be implemented using OAuth, with logins by username and password, Facebook, Google and other services.

Digital Signature

To prevent tampering of the data, a digital signature is included as a header in every request. The header name is X-Checksum and it is calculated using HMAC-SHA1 of the JSON representation of an object including url, query parameters and request body.

Media Types

Where applicable this API uses the JSON media-type to represent resources states and affordances.

Requests with a message-body are using plain JSON to set or update resource states.

Error States

The common HTTP Response Status Codes are used.

Resource Group 

Payback API Root 

Payback API entry point.

This resource does not have any attributes.

Retrieve the Entry Point
/
  • Response  204

User 

Users related resources of the Payback API

User 

A single User object. The User resource is the central resource in the Payback API. It represents one user of the service.

The User resource has the following attributes:

  • id — Username of the User
  • email — Email of the User
Retrieve a single User
/users/{id}

This method is only available for the authenticated user.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "id": "johndoe",
    "email": "johndoe@example.com"
}
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "User 'johndoe' does not exist." }
Update a single User
/users/{id}

This method is only available for the authenticated user. email is the only modifiable field.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

  • RequestToggle
  • Headers
    Content-Type: application/json
    Body
    {
    "email": "newemail@example.com"
}
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "id": "johndoe",
    "email": "johndoe@example.com"
}
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Cannot update field 'whatever'" }
or
{ "error": "Invalid checksum" }
or
{ "error": "Email 'john@example.com' already exists." }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "User 'johndoe' does not exist." }
Delete a User
/users/{id}

This method is only available for the authenticated user.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

  • Response  204
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "User 'johndoe' does not exist." }

Debt 

A single Debt object. The Debt resource represents a debt that a User has on another User.

A positive value means that this User owes something to another User, a negative value means that this User is owed by another User.

The Debt resource has the following attributes:

  • debtId — Id of a Debt of a User (read-only)
  • creditor — User that credits the debt (read-only)
  • debtor — User that owes the creditor (read-only)
  • originalValue — Money that we owe or are owed by the User above (read-only)
  • value — Money that we owe or are owed by the User above
  • currency — Money currency of the value (read-only)
  • created — Date (ISO 8601) the Debt was created (read-only)
  • modified — Date (ISO 8601) the Debt was last modified (read-only, not const)
Retrieve a single Debt
/users/{id}/debts/{debtId}{?currency}

This method is only available for the authenticated user.

  • Parameters
  • currency
    string (optional) Example: EUR

    Currency

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "debtId": 1,
    "creditor": "john",
    "debtor": "janeroe",
    "originalValue": 100,
    "value": 0,
    "currency": "EUR",
    "created": "2014-04-14T11:29Z",
    "modified": "2014-04-15T09:10Z"
}
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "Debt '2' for user 'johndoe' does not exist." }
Update a single Debt
/users/{id}/debts/{debtId}{?currency}

This method is only available for the authenticated user. The only modifiable field is value.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

    debtId
    number (required) Example: 1

    ID of the Debt of a User

  • RequestToggle
  • Headers
    Content-Type: application/json
    Body
    {
    "value": 0,
    "currency": "EUR"
}
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "debtId": 1,
    "creditor": "john",
    "debtor": "janeroe",
    "originalValue": 100,
    "value": 0,
    "currency": "EUR",
    "created": "2014-04-14T11:29Z",
    "modified": "2014-04-15T09:10Z"
}
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Cannot update field 'whatever'" }
or
{ "error": "Invalid checksum" }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "Debt '2' for user 'johndoe' does not exist." }
Delete a Debt
/users/{id}/debts/{debtId}{?currency}

This method is only available for the authenticated user.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

    debtId
    number (required) Example: 1

    ID of the Debt of a User

  • Response  204
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "Debt '2' for user 'johndoe' does not exist." }

Debts Collection 

Collection of all Debts that another User owes this User.

The Debts Collection resource has the following attribute:

  • total — Total number of Debts
  • balance — Total balance between owed money
  • credit — Money owed to this User
  • debit — Money that this User owes to the other Users
  • currency — Currency of balance, debit and credit
  • debts — Array of Debts
List all Debts of a User
/users/{id}/debts{?currency}

This method is only available for the authenticated user.

  • Parameters
  • currency
    string (optional) Example: EUR

    Currency

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "total": 2,
    "balance": -3.4,
    "credit": 0,
    "debit": 3.4,
    "currency": "EUR",
    "debts":
    [
        {
            "debtId": 1,
            "creditor": "john",
            "debtor": "janeroe",
            "originalValue": 100,
            "value": 0,
            "currency": "EUR",
            "created": "2014-04-14T11:29Z",
            "modified": "2014-04-15T09:10Z"
        },
        {
            "debtId": 2,
            "creditor": "smith",
            "debtor": "john",
            "user": "smith",
            "originalValue": 5.4,
            "value": 3.4,
            "currency": "EUR",
            "created": "2014-04-16T08:30Z",
            "modified": "2014-04-17T10:30Z"
        }
    ]
}
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
Create a new Debt
/users/{id}/debts{?currency}

This method is only available for the authenticated user.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

  • RequestToggle
  • Headers
    Content-Type: application/json
    Body
    {
    "user": "johndoe",
    "value": 100,
    "currency": "EUR"
}
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "created": [
        {
            "debtId": 2,
            "creditor": "smith",
            "debtor": "john",
            "user": "smith",
            "originalValue": 5.4,
            "value": 3.4,
            "currency": "EUR",
            "created": "2014-04-16T08:30Z",
            "modified": "2014-04-17T10:30Z"
        }
    ],
    "updated": [
        {
            "debtId": 1,
            "creditor": "john",
            "debtor": "janeroe",
            "originalValue": 100,
            "value": 0,
            "currency": "EUR",
            "created": "2014-04-14T11:29Z",
            "modified": "2014-04-15T09:10Z"
        }
    ]
}
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "User 'johndoe' does not exist." }
or
{ "error": "Value '0.0001' is invalid." }

Friend 

A single Friend object. The Friend resource represents a friend of a User.

The Friend resource has the following attributes:

  • id — Username of a Friend
Retrieve a single Friend
/users/{id}/friends/{friendId}

This method is only available for the authenticated user.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

    friendId
    string (required) Example: jane

    ID of a Friend of a User

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "id": "johndoe"
}
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "User 'johndoe' does not exist or is not a friend." }
Delete a single Friend
/users/{id}/friends/{friendId}

This method is only available for the authenticated user.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

    friendId
    string (required) Example: jane

    ID of a Friend of a User

  • Response  204
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "User 'johndoe' does not exist or is not a friend." }

Friends Collection 

Collection of all Users that are Friends of a User.

This is a one-way only friendship and it is used to provide quick access to Users that are commonly used in the transactions.

The Friends Collection resource has the following attributes:

  • total — Total number of Friends
  • friends — Array of Friends (not detailed)
List all Friends of a User
/users/{id}/friends

This method is only available for the authenticated user.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "total": 2,
    "friends": 
    [
        { "id": "janeroe" },
        { "id": "smith" }
    ]
}
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
Create a Friend of a User
/users/{id}/friends

This method is only available for the authenticated user.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

  • RequestToggle
  • Headers
    Content-Type: application/json
    Body
    { "id": "johndoe" }
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    { "id": "johndoe" }
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "User 'johndoe' already friended." }
or
{ "error": "No permission" }
or
{ "error": "Invalid checksum" }
  • Response  404Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "User 'johndoe' does not exist." }
Delete all Friends of a User
/users/{id}/friends

This method is only available for the authenticated user.

  • Parameters
  • id
    string (required) Example: john

    ID of the User

  • Response  204
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }

Users Collection 

Collection of all Users.

The User Collection resource has the following attributes:

  • total — Total number of Users
  • Users — Array of Users (not detailed)
List all Users
/users{?search}
  • Parameters
  • search
    string (optional) Example: jo

    Fuzzy search. Only users that have an id or email related to the search parameter are returned.

  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "total": 2,
    "users": 
    [
        { "id": "johndoe" },
        { "id": "janeroe" }
    ]
}
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "No permission" }
or
{ "error": "Invalid checksum" }
Create a User
/users{?search}
  • Parameters
  • search
    string (optional) Example: jo

    Fuzzy search. Only users that have an id or email related to the search parameter are returned.

  • RequestToggle
  • Headers
    Content-Type: application/json
    Body
    { "id": "john", "email": "john@example.com", "passwordHash": "abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcd" }
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    { "id": "john", "email": "john@example.com" }
  • Response  403Toggle
  • Headers
    Content-Type: application/json
    Body
    { "error": "User 'john' already exists." }
or
{ "error": "Email 'john@example.com' already exists." }
or
{ "error": "Invalid checksum" }

Exchange Rates Collection 

Collection of all exchange rates.

The Exchange Rates resource has the following attributes:

  • base — Currency used as base for the rates
  • rates — Exchange rates
List all Exchange Rates
/exchangeRates
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
    "base": "EUR",
    "rates": {
        "AUD": 1.4684,
        "BGN": 1.9558,
        "BRL": 3.0485,
        "CAD": 1.4976,
        "CHF": 1.2211
    }
}

Generated by aglio on 03 Jun 2014