Endpoints

All endpoints need an access token that identifies a user who has given permission to your app.

Starting a transaction

POST /1.0/transactions

Parameters:

  • description: Textual description of what the transaction will involve

This will create a transaction, owned by the authenticated user. Still, this transaction is not protected against fraud until the second party joins it.

The response is the newly created transaction, including its id, starting date, user1 id (the user who created it), and a human code that can be used to univocally refer to the transaction:

{ "description": "Selling train ticket to New Jersey",
  "user1_id": "32d72hcc547",
  "user2_id": null,
  "code": "skyline34",
  "app_id": "3g7376gc7hg3",
  "started_at": null }

The code can be used to tell another user to join the transaction using Kevin by redirecting to http://kevin.chat/skyline34 . In general, all transactions can be managed by users talking directly to the bot.

Joining a transaction

POST /1.0/transactions/:transaction_id/join

This will make the authenticated user join the transaction. The response contains the newly updated transaction information:

{ "id": "c6br4t37nc9",
  "description": "Selling train ticket to New Jersey",
  "user1_id": "32d72hcc547",
  "user2_id": "8rn4c278m10",
  "code": "skyline34",
  "app_id": "3g7376gc7hg3",
  "started_at": "2016/06/01 09:32:02" }

The transaction is now protected, and its generated receipt can be retrieved.

Retrieving a transaction

GET /1.0/transactions/:transaction_id

This will return a transaction's information if the authenticated user is part of the transaction (either created it or joined it), and return a forbidden error otherwise.

{ "id": "c6br4t37nc9",
  "description": "Selling train ticket to New Jersey",
  "user1_id": "32d72hcc547",
  "user2_id": "8rn4c278m10",
  "code": "skyline34",
  "app_id": "3g7376gc7hg3",
  "started_at": "2016/06/01 09:32:02" }

Retrieving a transaction's receipt

GET /1.0/transactions/:transaction_id/receipt

Returns a picture that includes a QR code, which represents a transaction and shows it's protected. An app can use this endpoint to resend the receipt to a user in a confirmation email, if desired.

{ "url": "https://traity-gloria.s3.amazonaws.com/transactions/S/w/h/M/3/x/0/F" }

Posting a review

POST /1.0/transactions/:transaction_id/reviews

Parameters:

  • overall_rating: Integer between 1 and 5 representing the overall satisfaction with the other party.
  • text: Textual content of the review describing the experience.

This will review the transaction on behalf of the authenticated user. It returns the review created:

{ "scores": [{ "field": "overview", "rating": 4 }],
  "user_id": "32d72hcc547",
  "transaction_id": "c6br4t37nc9",
  "text": "Great guy, on time. Product as expected" }

Retrieving a transaction's reviews

GET /1.0/transactions/:transaction_id/reviews

Returns all reviews associated to a transaction

[{ "scores": [{ "field": "overview", "rating": 4 }],
   "user_id": "32d72hcc547",
   "transaction_id": "c6br4t37nc9",
   "text": "Great guy, on time. Product as expected" },
 { "scores": [{ "field": "overview", "rating": 5 }],
   "user_id": "8rn4c278m10",
   "transaction_id": "c6br4t37nc9",
   "text": "Nice person, a pleasure to transact with her" }]

Claiming a transaction

POST /1.0/transactions/:transaction_id/claim

Parameters:

  • text: Textual description of the claim.

This will send a claim to a specific transaction. Traity will get in touch with the user to know about the case and compensate the user with up to $100, in case it's needed.

Retrieving a user's access token

GET /1.0/apps/users/:user_id/token

Parameters:

  • signature: A widget signature for the desired user id

This will retrieve an access token when the app's user has accepted the app's permissions through a widget, and not through the OAuth permissions acceptance flow.