Trustap API API Reference

The Trustap API is a REST-based API for managing user data and transactions for Trustap users.

Note that, like Stripe, all API price and charge fields expect amounts to be provided in a currency's smallest unit. See the Stripe documentation for more details.

API Keys

Some endpoints such as /charge endpoints can be accessed directly using an API key. API keys are provided as the "username" portion of a basic auth authentication. For example, the Trustap fee for a new online transaction can be determined using the following cURL request with an API key:

curl -u '<api_key>': 'https://dev.stage.trustap.com/api/v1/charge?currency=eur&price=1234'

Deprecation

Deprecated endpoints are tagged with the word DEPRECATED at the start of their description. The deprecation message will describe what endpoints/approach should be used instead.

Note that deprecated endpoints will not be removed from the current version of the API, but their use is discouraged. Furthermore, migrating to later major versions of the API will be made easier by avoiding deprecated endpoints.

Production

This documentation references the staging environment of the Trustap API, which is available at https://dev.stage.trustap.com and uses the trustap-stage realm during authentication. This environment can be used for implementing and testing features using test credit cards, bank accounts, etc.

When all features using Trustap have been implemented and tested sufficiently, the production environment of the Trustap API can be used to process actual currency. This environment is available at https://dev.trustap.com and uses the trustap realm during authentication.

Note that only your client ID will be the same in the staging and production Trustap API environments; your client secret and API key will be different in the two environments.

API Endpoint
https://dev.stage.trustap.com/api/v1
Contact: help@trustap.com
Schemes: https
Version: 0.1.0

Authentication

APIKey

OAuth2

flow
accessCode
authorizationUrl
https://sso.trustap.com/auth/realms/trustap-stage/protocol/openid-connect/auth
tokenUrl
https://sso.trustap.com/auth/realms/trustap-stage/protocol/openid-connect/token

Online Transactions

Get the supported carriers

GET /supported_carriers

This returns the carriers that are currently supported for automated tracking in the online model. The carrier name should be shown to users but the code should be submitted to the /track endpoint when submitting tracking details. Likewise, when showing a transaction to the user, the carrier field stored with the transaction should be used to index these carriers and show the human-readable name of the carrier to the user, if this index is found.

200 OK

OK

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "code": "an-post",
    "name": "An Post"
  },
  {
    "code": "fedex",
    "name": "FedEx"
  },
  {
    "code": "ups",
    "name": "UPS"
  },
  {
    "code": "usps",
    "name": "USPS"
  }
]

Get the Trustap fee for a transaction

GET /charge

This returns the Trustap fee, in the currency's smallest unit, for a transaction involving goods with the supplied price. See the Stripe documentation for more details.

currency

The currency that the price is specified in.

type
string
in
query
price

The price of the goods being sold in this transaction, in the currency's smallest unit. For example, if a trading card is being sold for $12.34 (with currency as usd), then the request for the charge for this transaction would be /charge?price=1234&currency=usd.

type
integer (int64)
in
query
200 OK

OK

400 Bad Request

Bad Request

code can be one of the following:

  • currency_missing
  • invalid_price
  • negative_price
  • price_too_low
  • unsupported_currency
Response Content-Types: application/json
Response Example (200 OK)
{
  "currency": "eur",
  "charge": 78,
  "charge_calculator_version": 5
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Create a new transaction

POST /me/transactions

A request to this endpoint must be preceded by a call to /charge with the price of the goods specified in price.

role: Role
currency: Currency
price: integer (int64)

The price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

description: string

A description of the goods being sold.

charge: integer (int64)

The charge value returned from a request to /charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /charge.

Request Content-Types: application/json
Request Example
{
  "role": "seller",
  "currency": "eur",
  "price": 1234,
  "description": "Soccer ticket",
  "charge": 78,
  "charge_calculator_version": 5
}
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

  • incorrect_calc_version
  • incorrect_charge
  • invalid_calc_version
  • negative_price
  • price_too_low
Response Content-Types: application/json
Response Example (201 Created)
{
  "id": 1309,
  "status": "created",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Get online transactions for the logged-in user

GET /me/transactions

Transactions are currently sorted by ID.

after_id

Only return transactions that were created chronologically after the transaction with this ID (i.e. with smaller IDs)

type
integer (int64) , { x ∈ ℤ | x ≥ 0 }
in
query
limit

The maximum number of transactions to return

type
integer (int64) , { x ∈ ℤ | 1 ≤ x ≤ 50 } 25
in
query

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_after_id
  • invalid_limit
Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": 1309,
    "status": "created",
    "currency": "eur",
    "price": 1234,
    "charge": 78,
    "description": "Soccer ticket",
    "created": "2019-12-25T09:00:00.000Z",
    "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
    "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4"
  },
  {
    "id": 609,
    "status": "created",
    "currency": "eur",
    "price": 1234,
    "charge": 78,
    "description": "Soccer ticket",
    "created": "2018-12-25T09:00:00.000Z",
    "buyer_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
    "join_code": "c9cd6a9d-1096-4d38-b4aa-2c354beac845"
  }
]
Response Example (400 Bad Request)
{
  "code": "invalid_after_id",
  "error": "invalid after id"
}

Get a transaction using a join code

GET /transactions
join_code

(no description)

type
string
in
query

OK

400 Bad Request

Bad Request

code can be one of the following:

  • join_code_missing
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "created",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4"
}
Response Example (400 Bad Request)
{
  "code": "join_code_missing",
  "error": "`join_code` query parameter is required"
}

Join a transaction using a join code

PUT /transactions

A transaction can't be joined using its ID, because only the buyer and seller of a transaction can access a transaction using its ID.

join_code

(no description)

type
string
in
query

OK

400 Bad Request

Bad Request

code can be one of the following:

  • join_code_missing
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "joined",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "join_code_missing",
  "error": "`join_code` query parameter is required"
}

Reject a transaction by its join code

POST /transactions-by-join-code/{joinCode}/reject

A transaction can't be rejected using its ID, because only the buyer and seller of a transaction can access a transaction using its ID.

joinCode

(no description)

type
string
in
path

OK

400 Bad Request

Bad Request

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "rejected",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "denied": "2019-12-25T10:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Get a transaction by its ID

GET /transactions/{transactionId}
transactionId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_id
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "joined",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Get multiple transactions by their IDs

GET /batch/transactions

This endpoint takes a required ids parameter that contains a comma-separated list of transaction IDs, and returns the transactions corresponding to those IDs. A maximum of 50 IDs may be provided, results are returned in the order specified in ids, and duplicates are preserved. Transactions that couldn't be found will be returned as null values in the result array. The following example request results in the 200 OK response described below, assuming that the transaction with ID 1990 couldn't be found:

https://dev.stage.trustap.com/api/v1/batch/transactions?ids=1309,609,1990,609
ids

A comma-separated list of transaction IDs

type
string
in
query

OK

400 Bad Request

Bad Request

code can be one of the following:

  • ids_missing
  • invalid_id
  • too_many_ids
Response Content-Types: application/json
Response Example (200 OK)
[
  [
    {
      "id": 1309,
      "status": "created",
      "currency": "eur",
      "price": 1234,
      "charge": 78,
      "description": "Soccer ticket",
      "created": "2019-12-25T09:00:00.000Z",
      "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
      "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4"
    },
    {
      "id": 609,
      "status": "created",
      "currency": "eur",
      "price": 1234,
      "charge": 78,
      "description": "Soccer ticket",
      "created": "2018-12-25T09:00:00.000Z",
      "buyer_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
      "join_code": "c9cd6a9d-1096-4d38-b4aa-2c354beac845"
    },
    null,
    {
      "id": 609,
      "status": "created",
      "currency": "eur",
      "price": 1234,
      "charge": 78,
      "description": "Soccer ticket",
      "created": "2018-12-25T09:00:00.000Z",
      "buyer_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
      "join_code": "c9cd6a9d-1096-4d38-b4aa-2c354beac845"
    }
  ]
]
Response Example (400 Bad Request)
{
  "code": "ids_missing",
  "error": "`ids` query parameter is required"
}

Get the Stripe client secret for this transaction

GET /transactions/{transactionId}/stripe_client_secret

This endpoint is used for the asynchronous payment flow using Stripe. The client_secret returned from this endpoint should be passed to stripe.confirmCardPayment to start the payment process.

transactionId

(no description)

type
integer (int64)
in
path
200 OK

OK

400 Bad Request

Bad Request

code can be one of the following:

  • already_paid
  • invalid_id
  • not_accepted: This transaction was created from a listing but the listing's creator has not yet accepted this transaction.
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "client_secret": "string"
}
Response Example (400 Bad Request)
{
  "code": "already_paid",
  "error": "payment already made"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Set payment details and process payment for this transaction

POST /transactions/{transactionId}/pay

DEPRECATED

Payment should be processed using the asynchronous payment flow (see /transactions/{transactionId}/stripe_client_secret).

stripe_token: string

stripe_token is a card token ID received from Stripe. It is generated using a publishable Stripe key from Trustap. See https://stripe.com/docs/stripe-js and https://stripe.com/docs/checkout for methods for generating this token.

transactionId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "stripe_token": "string"
}

OK

400 Bad Request

Bad Request

code can be one of the following:

  • already_paid
  • card_declined
  • expired_card
  • incorrect_cvc
  • insufficient_funds
  • invalid_id
  • not_accepted: This transaction was created from a listing but the listing's creator has not yet accepted this transaction.
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "paid",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "already_paid",
  "error": "payment already made"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Set postal tracking details for this transaction

POST /transactions/{transactionId}/track

After the tracking information has been submitted then the state of the transaction will be updated asynchronously by Trustap once the delivery of the item has been confirmed, at which point the delivered field of the transaction will be set.

carrier: CarrierName
tracking_code: string
transactionId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "carrier": "ups",
  "tracking_code": "***"
}

OK

400 Bad Request

Bad Request

code can be one of the following:

  • empty_carrier
  • empty_tracking_code
  • invalid_id
403 Forbidden

Forbidden

code can be one of the following:

  • not_seller
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "tracked",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}
Response Example (400 Bad Request)
{
  "code": "empty_carrier",
  "error": "`carrier` parameter is required"
}
Response Example (403 Forbidden)
{
  "code": "not_seller",
  "error": "current user is not seller"
}

Submit a detailed complaint for this transaction

POST /transactions/{transactionId}/complain_with_description
description: string
transactionId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "description": "Item was fake"
}

OK

400 Bad Request

Bad Request

code can be one of the following:

  • complaint_period_ended_prematurely: The buyer has already ended the complaint period.
  • complaint_period_expired
  • invalid_id
  • unconfirmed_delivery: The complaint period for this transaction has not yet started.
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "complained",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  },
  "delivered": "2019-12-25T13:00:00.000Z",
  "complained": "2019-12-25T14:00:00.000Z",
  "complaint": {
    "description": "Item was fake"
  }
}
Response Example (400 Bad Request)
{
  "code": "complaint_period_expired",
  "error": "complaint period has expired"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Flag a complaint for this transaction

POST /transactions/{transactionId}/complain

DEPRECATED

Complaints should be submitted using /transactions/{transactionId}/complain_with_description.

transactionId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • complaint_period_ended_prematurely: The buyer has already ended the complaint period.
  • complaint_period_expired
  • invalid_id
  • unconfirmed_delivery: The complaint period for this transaction has not yet started.
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "complained",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  },
  "delivered": "2019-12-25T13:00:00.000Z",
  "complained": "2019-12-25T14:00:00.000Z",
  "complaint": {
    "description": ""
  }
}
Response Example (400 Bad Request)
{
  "code": "complaint_period_expired",
  "error": "complaint period has expired"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

End the complaint period for this transaction

POST /transactions/{transactionId}/end_complaint_period
transactionId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • complaint_period_expired
  • invalid_id
  • unconfirmed_delivery: The complaint period for this transaction has not yet started.
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "complaint_period_ended",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  },
  "delivered": "2019-12-25T13:00:00.000Z",
  "complaint_period_ended": "2019-12-25T14:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "complaint_period_expired",
  "error": "complaint period has expired"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Allow this listing-based transaction to proceed

POST /transactions/{transactionId}/accept_listing_transaction

"Listing transactions" are transactions created from listings (using the /create_transaction endpoints for listings). Listings transactions for online transactions must be accepted by the creator of the listing using /accept_listing_transaction in order to proceed.

transactionId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • no_listing: This transaction wasn't created from a listing
  • already_accepted
  • already_rejected
403 Forbidden

Forbidden

code can be one of the following:

  • not_creator
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "listing_id": 1990,
  "status": "paid",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "accepted_by_listing_creator": "2019-12-25T11:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "already_accepted",
  "error": "transaction already accepted"
}
Response Example (403 Forbidden)
{
  "code": "not_creator",
  "error": "current user is not the creator for the source listing"
}

Cancel this listing-based transaction

POST /transactions/{transactionId}/reject_listing_transaction

"Listing transactions" are transactions created from listings (using the /create_transaction endpoints for listings). Listings transactions for online transactions must be accepted by the creator of the listing using /accept_listing_transaction in order to proceed. This endpoint instead rejects the listing transaction.

transactionId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • no_listing: This transaction wasn't created from a listing
  • already_accepted
  • already_rejected
403 Forbidden

Forbidden

code can be one of the following:

  • not_creator
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "listing_id": 1990,
  "status": "paid",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "rejected_by_listing_creator": "2019-12-25T11:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "already_accepted",
  "error": "transaction already accepted"
}
Response Example (403 Forbidden)
{
  "code": "not_creator",
  "error": "current user is not the creator for the source listing"
}

Online Single-use Listings

Create a new single-use listing for the logged-in user

POST /me/single_use_listings/create

Single-use listings are disabled once payment has been submitted for a transaction created from it.

role: Role
description: string

A description of the goods being sold.

currency: Currency
price: integer (int64)

The price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

charge: integer (int64)

The charge value returned from a request to /charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /charge.

Request Content-Types: application/json
Request Example
{
  "role": "seller",
  "description": "Soccer ticket",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "charge_calculator_version": 5
}
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

* `invalid_role`: '' is not a valid role
Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Soccer ticket",
  "currency": "eur",
  "pricing": {
    "price": 1234,
    "charge": 78
  },
  "created": "2019-12-25T09:00:00.000Z"
}

Create a new single-use listing for the logged-in user

POST /me/single_use_listings

DEPRECATED

Single-use-listings for online transactions should be created using /me/single_use_listings/create.

Single-use listings are disabled once payment has been submitted for a transaction created from it.

201 Created

Created

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "created": "2019-12-25T09:00:00.000Z"
}

Get a listing by its ID

GET /single_use_listings/{listingId}
listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "created": "2019-12-25T09:00:00.000Z"
}

Delete this listing

DELETE /single_use_listings/{listingId}
listingId

(no description)

type
integer (int64)
in
path
204 No Content

No Content

404 Not Found

Not Found

Response Content-Types: application/json

Set description for this listing

POST /single_use_listings/{listingId}/set_description
description: string
listingId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "description": "Soccer ticket"
}
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z"
}

Set pricing for this listing

POST /single_use_listings/{listingId}/set_pricing
currency: Currency
price: integer (int64)

The price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

charge: integer (int64)

The charge value returned from a request to /charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /charge.

listingId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "charge_calculator_version": 5
}
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z"
}

Create a transaction from this listing

POST /single_use_listings/{listingId}/create_transaction
listingId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • listing_is_disabled
  • no_listing_currency: The source listing doesn't have a currency.
  • no_listing_price: The source listing doesn't have pricing.
  • no_listing_descr: The source listing doesn't have a description.
  • is_listing_creator: The current user created this listing.
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "joined",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Disable this listing

POST /single_use_listings/{listingId}/disable

Calling /create_transaction on a disabled listing will return a 400 response.

listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "disabled": "2019-12-25T10:00:00.000Z"
}

Enable this listing

POST /single_use_listings/{listingId}/enable
listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z"
}

Online Multi-use Listings

Create a new multi-use listing for the logged-in user

POST /me/multi_use_listings/create

Multi-use listings are disabled once payment has been submitted for a transaction created from it.

role: Role
description: string

A description of the goods being sold.

currency: Currency
price: integer (int64)

The price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

charge: integer (int64)

The charge value returned from a request to /charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /charge.

Request Content-Types: application/json
Request Example
{
  "role": "seller",
  "description": "Soccer ticket",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "charge_calculator_version": 5
}
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

* `invalid_role`: '' is not a valid role
Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Soccer ticket",
  "currency": "eur",
  "pricing": {
    "price": 1234,
    "charge": 78
  },
  "created": "2019-12-25T09:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Get a listing by its ID

GET /multi_use_listings/{listingId}
listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "created": "2019-12-25T09:00:00.000Z"
}

Delete this listing

DELETE /multi_use_listings/{listingId}
listingId

(no description)

type
integer (int64)
in
path
204 No Content

No Content

404 Not Found

Not Found

Response Content-Types: application/json

Set description for this listing

POST /multi_use_listings/{listingId}/set_description
description: string
listingId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "description": "Soccer ticket"
}
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z"
}

Set pricing for this listing

POST /multi_use_listings/{listingId}/set_pricing
currency: Currency
price: integer (int64)

The price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

charge: integer (int64)

The charge value returned from a request to /charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /charge.

listingId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "charge_calculator_version": 5
}
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z"
}

Create a transaction from this listing

POST /multi_use_listings/{listingId}/create_transaction
listingId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • listing_is_disabled
  • no_listing_currency: The source listing doesn't have a currency.
  • no_listing_price: The source listing doesn't have pricing.
  • no_listing_descr: The source listing doesn't have a description.
  • is_listing_creator: The current user created this listing.
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "joined",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Disable this listing

POST /multi_use_listings/{listingId}/disable

Calling /create_transaction on a disabled listing will return a 400 response.

listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "disabled": "2019-12-25T10:00:00.000Z"
}

Enable this listing

POST /multi_use_listings/{listingId}/enable
listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z"
}

F2F Transactions

Get the Trustap fee for a face-to-face transaction

GET /p2p/charge

This returns the Trustap fee, in the currency's smallest unit, for a transaction involving goods with the supplied price. See the Stripe documentation for more details.

currency

The currency that the price is specified in.

type
string
in
query
price

The price of the goods being sold in this transaction, in the currency's smallest unit. For example, if a trading card is being sold for $12.34 (with currency as usd), then the request for the charge for this transaction would be /p2p/charge?price=1234&currency=usd.

type
integer (int64)
in
query
200 OK

OK

400 Bad Request

Bad Request

code can be one of the following:

  • currency_missing
  • invalid_price
  • negative_price
  • price_too_low
  • unsupported_currency
Response Content-Types: application/json
Response Example (200 OK)
{
  "currency": "eur",
  "charge": 78,
  "charge_calculator_version": 2
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Create a new face-to-face transaction

POST /p2p/me/transactions

Note that this endpoint is similar to POST /me/transactions but takes deposit_price and deposit_charge fields instead of the price and charge fields.

role: Role
currency: Currency
description: string

A description of the goods being sold.

deposit_price: integer (int64)
deposit_charge: integer (int64)
charge_calculator_version: integer (int64)
skip_remainder: boolean

If skip_remainder is true then this transaction will move to the "confirm handover" step after the deposit has been accepted.

Request Content-Types: application/json
Request Example
{
  "role": "seller",
  "currency": "eur",
  "description": "Soccer ticket",
  "deposit_price": 1234,
  "deposit_charge": 78,
  "charge_calculator_version": 2
}
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

  • incorrect_calc_version
  • incorrect_charge
  • invalid_calc_version
  • negative_price
  • price_too_low
Response Content-Types: application/json
Response Example (201 Created)
{
  "id": 1309,
  "status": "created",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Get face-to-face transactions for the logged-in user

GET /p2p/me/transactions

Transactions are currently sorted by ID.

after_id

Only return transactions that were created chronologically after the transaction with this ID (i.e. with smaller IDs)

type
integer (int64) , { x ∈ ℤ | x ≥ 0 }
in
query
limit

The maximum number of transactions to return

type
integer (int64) , { x ∈ ℤ | 1 ≤ x ≤ 50 } 25
in
query

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_after_id
  • invalid_limit
Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": 1309,
    "status": "funds_released",
    "currency": "eur",
    "deposit_pricing": {
      "price": 1234,
      "charge": 78
    },
    "description": "Soccer ticket",
    "skip_remainder": false,
    "created": "2019-12-25T09:00:00.000Z",
    "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
    "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
    "joined": "2019-12-25T10:00:00.000Z",
    "deposit_paid": "2019-12-25T11:00:00.000Z",
    "deposit_accepted": "2019-12-25T12:00:00.000Z",
    "pricing": {
      "price": 5000,
      "charge": 190
    },
    "priced": "2019-12-25T13:00:00.000Z",
    "remainder_paid": "2019-12-25T14:00:00.000Z",
    "seller_handover_confirmed": "2019-12-25T15:00:00.000Z",
    "buyer_handover_confirmed": "2019-12-25T16:00:00.000Z",
    "funds_released": "2019-12-25T17:00:00.000Z"
  },
  {
    "id": 609,
    "status": "created",
    "currency": "eur",
    "deposit_pricing": {
      "price": 1234,
      "charge": 78
    },
    "description": "Soccer ticket",
    "skip_remainder": false,
    "created": "2018-12-25T09:00:00.000Z",
    "buyer_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
    "join_code": "c9cd6a9d-1096-4d38-b4aa-2c354beac845"
  }
]
Response Example (400 Bad Request)
{
  "code": "invalid_after_id",
  "error": "invalid after id"
}

Get a transaction by its join code

GET /p2p/transactions_by_join_code/{joinCode}
joinCode

(no description)

type
string
in
path

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "created",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4"
}

Join a transaction by its join code

POST /p2p/transactions_by_join_code/{joinCode}/join
joinCode

(no description)

type
string
in
path

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "joined",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z"
}

Reject a transaction by its join code

POST /p2p/transactions_by_join_code/{joinCode}/reject
joinCode

(no description)

type
string
in
path

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "joined",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "rejected": "2019-12-25T10:00:00.000Z"
}

Get a transaction by its ID

GET /p2p/transactions/{transactionId}
transactionId

(no description)

type
integer (int64)
in
path

OK

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "joined",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z"
}

Get multiple transactions by their IDs

GET /p2p/batch/transactions

This endpoint takes a required ids parameter that contains a comma-separated list of transaction IDs, and returns the transactions corresponding to those IDs. A maximum of 50 IDs may be provided, and results are returned in the order specified in ids, and duplicates are preserved. Transactions that couldn't be found will be returned as null values in the result array. The following example request results in the 200 OK response described below, assuming that the transaction with ID 1990 couldn't be found:

https://dev.stage.trustap.com/api/v1/p2p/batch/transactions?ids=1309,609,1990,609
ids

A comma-separated list of transaction IDs

type
string
in
query

OK

400 Bad Request

Bad Request

code can be one of the following:

  • ids_missing
  • invalid_id
  • too_many_ids
Response Content-Types: application/json
Response Example (200 OK)
[
  [
    {
      "id": 1309,
      "status": "funds_released",
      "currency": "eur",
      "deposit_pricing": {
        "price": 1234,
        "charge": 78
      },
      "description": "Soccer ticket",
      "skip_remainder": false,
      "created": "2019-12-25T09:00:00.000Z",
      "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
      "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
      "joined": "2019-12-25T10:00:00.000Z",
      "deposit_paid": "2019-12-25T11:00:00.000Z",
      "deposit_accepted": "2019-12-25T12:00:00.000Z",
      "pricing": {
        "price": 5000,
        "charge": 190
      },
      "priced": "2019-12-25T13:00:00.000Z",
      "remainder_paid": "2019-12-25T14:00:00.000Z",
      "seller_handover_confirmed": "2019-12-25T15:00:00.000Z",
      "buyer_handover_confirmed": "2019-12-25T16:00:00.000Z",
      "funds_released": "2019-12-25T17:00:00.000Z"
    },
    {
      "id": 609,
      "status": "created",
      "currency": "eur",
      "deposit_pricing": {
        "price": 1234,
        "charge": 78
      },
      "description": "Soccer ticket",
      "skip_remainder": false,
      "created": "2018-12-25T09:00:00.000Z",
      "buyer_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
      "join_code": "c9cd6a9d-1096-4d38-b4aa-2c354beac845"
    },
    null,
    {
      "id": 609,
      "status": "created",
      "currency": "eur",
      "deposit_pricing": {
        "price": 1234,
        "charge": 78
      },
      "description": "Soccer ticket",
      "skip_remainder": false,
      "created": "2018-12-25T09:00:00.000Z",
      "buyer_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
      "join_code": "c9cd6a9d-1096-4d38-b4aa-2c354beac845"
    }
  ]
]
Response Example (400 Bad Request)
{
  "code": "ids_missing",
  "error": "`ids` query parameter is required"
}

Cancel this transaction with a description

POST /p2p/transactions/{transactionId}/cancel_with_description

If a transaction is cancelled after the deposit has been paid then the deposit (excluding the Trustap fee) will be returned to the buyer.

description: string
transactionId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "description": "Found another buyer"
}

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "cancelled",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "cancelled": "2019-12-25T11:00:00.000Z",
  "cancellation": {
    "reason": "Found another buyer"
  }
}

Cancel this transaction

POST /p2p/transactions/{transactionId}/cancel

DEPRECATED

Transactions should be cancelled using /transactions/{transactionId}/cancel_with_description.

transactionId

(no description)

type
integer (int64)
in
path

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "cancelled",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "cancelled": "2019-12-25T11:00:00.000Z",
  "cancellation": {
    "reason": ""
  }
}

Get the Stripe client secret for this transaction

GET /p2p/transactions/{transactionId}/deposit_stripe_client_secret

This endpoint is used for the asynchronous payment flow using Stripe. The client_secret returned from this endpoint should be passed to stripe.confirmCardPayment to start the payment process.

transactionId

(no description)

type
integer (int64)
in
path
200 OK

OK

400 Bad Request

Bad Request

code can be one of the following:

  • deposit_already_paid
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "client_secret": "***"
}
Response Example (400 Bad Request)
{
  "code": "deposit_already_paid",
  "error": "deposit payment already made"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Set payment details and process payment for the deposit of this transaction

POST /p2p/transactions/{transactionId}/pay_deposit

DEPRECATED

This endpoint will be removed in v2 of this API.

Payment should instead be processed using the asynchronous payment flow (see /p2p/transactions/{transactionId}/deposit_stripe_client_secret).

stripe_charge_token: string
transactionId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "stripe_token": "***"
}

OK

400 Bad Request

Bad Request

code can be one of the following:

  • card_declined
  • deposit_already_paid
  • expired_card
  • incorrect_cvc
  • insufficient_funds
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "deposit_paid",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "deposit_already_paid",
  "error": "deposit payment already made"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Accept the deposit for this transaction

POST /p2p/transactions/{transactionId}/accept_deposit
transactionId

(no description)

type
integer (int64)
in
path

OK

403 Forbidden

Forbidden

code can be one of the following:

  • not_seller
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "deposit_accepted",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_accepted": "2019-12-25T12:00:00.000Z"
}
Response Example (403 Forbidden)
{
  "code": "not_seller",
  "error": "current user is not seller"
}

Skip the remainder for this transaction

POST /p2p/transactions/{transactionId}/skip_remainder

This will skip the remainder payment of this transaction, and the total price of the transaction will not need to be set. Note that this must be done before the total price of the transaction is set using /set_price.

transactionId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • price_already_set
403 Forbidden

Forbidden

code can be one of the following:

  • not_seller
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "remainder_skipped",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_accepted": "2019-12-25T12:00:00.000Z",
  "remainder_skipped": "2019-12-25T13:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}
Response Example (403 Forbidden)
{
  "code": "not_seller",
  "error": "current user is not seller"
}

Set the total price for this transaction

POST /p2p/transactions/{transactionId}/set_price

price is the total price of the item, and thus includes the price already paid for the deposit.

Note that this endpoint will return a remainder_too_low response if the difference between the total price and the deposit price is too low.

currency: Currency
price: integer (int64)

The price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

charge: integer (int64)

The charge value returned from a request to /p2p/charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /p2p/charge.

transactionId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "currency": "eur",
  "price": 5000,
  "charge": 190,
  "charge_calculator_version": 2
}

OK

400 Bad Request

Bad Request

code can be one of the following:

  • currency_mismatch: Pricing currency is different to the transaction's currency.
  • remainder_already_skipped
  • remainder_too_low: The difference between the total price of this transaction isn't larger than the deposit price.
403 Forbidden

Forbidden

code can be one of the following:

  • not_seller
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "deposit_accepted",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_accepted": "2019-12-25T12:00:00.000Z",
  "pricing": {
    "price": 5000,
    "charge": 190
  },
  "priced": "2019-12-25T13:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}
Response Example (403 Forbidden)
{
  "code": "not_seller",
  "error": "current user is not seller"
}

Get the Stripe client secret for this transaction

GET /p2p/transactions/{transactionId}/remainder_stripe_client_secret

This endpoint is used for the asynchronous payment flow using Stripe. The client_secret returned from this endpoint should be passed to stripe.confirmCardPayment to start the payment process.

transactionId

(no description)

type
integer (int64)
in
path
200 OK

OK

400 Bad Request

Bad Request

code can be one of the following:

  • missing_pricing: Pricing details have not yet been added to this transaction.
  • remainder_already_paid
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "client_secret": "***"
}
Response Example (400 Bad Request)
{
  "code": "remainder_already_paid",
  "error": "remainder payment already made"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Set payment details and process payment for the remainder of this transaction

POST /p2p/transactions/{transactionId}/pay_remainder

DEPRECATED

This endpoint will be removed in v2 of this API.

Payment should instead be processed using the asynchronous payment flow (see /p2p/transactions/{transactionId}/deposit_stripe_client_secret).

stripe_charge_token: string
transactionId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "stripe_token": "***"
}

OK

400 Bad Request

Bad Request

code can be one of the following:

  • card_declined
  • expired_card
  • incorrect_cvc
  • insufficient_funds
  • invalid_id
  • missing_pricing: Pricing details have not yet been added to this transaction.
  • remainder_already_paid
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "deposit_accepted",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_accepted": "2019-12-25T12:00:00.000Z",
  "pricing": {
    "price": 5000,
    "charge": 190
  },
  "priced": "2019-12-25T13:00:00.000Z",
  "remainder_paid": "2019-12-25T14:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "remainder_already_paid",
  "error": "remainder payment already made"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Get details of the buyer from this transaction

GET /p2p/transactions/{transactionId}/buyer_details
transactionId

(no description)

type
integer (int64)
in
path
200 OK

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "email": "string",
  "name": {
    "first": "string",
    "last": "string"
  },
  "phone": "string"
}

Submit a complaint for this transaction

POST /p2p/transactions/{transactionId}/complain
description: string
transactionId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "description": "Item was fake"
}

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "deposit_accepted",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_accepted": "2019-12-25T12:00:00.000Z",
  "pricing": {
    "price": 5000,
    "charge": 190
  },
  "priced": "2019-12-25T13:00:00.000Z",
  "remainder_paid": "2019-12-25T14:00:00.000Z",
  "complaint": {
    "description": "Item was fake"
  },
  "complained": "2019-12-25T15:00:00.000Z"
}

Confirm handover for this transaction

POST /p2p/transactions/{transactionId}/confirm_handover

Both parties should confirm the handover for a face-to-face transaction. The complaints period begins when the seller confirms the handover.

transactionId

(no description)

type
integer (int64)
in
path

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "seller_handover_confirmed",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_accepted": "2019-12-25T12:00:00.000Z",
  "pricing": {
    "price": 5000,
    "charge": 190
  },
  "priced": "2019-12-25T13:00:00.000Z",
  "remainder_paid": "2019-12-25T14:00:00.000Z",
  "seller_handover_confirmed": "2019-12-25T15:00:00.000Z"
}

Create a new face-to-face transaction with both users

POST /p2p/me/transactions/create_and_join

This endpoint is an optimised call that allows a transaction to be created and joined in a single request. It requires the user identified by join_user_id to have granted the p2p_tx:offline_create_join scope to the client that is performing the request.

Note that this endpoint is similar to POST /me/transactions but takes deposit_price and deposit_charge fields instead of the price and charge fields.

join_user_id: string

The user that will be joined to the new transaction when it is created. It cannot be the ID of the user making the request.

creator_role: Role

This is the role that will be given to the user making the request; the user specified by join_user_id will be given the complementary role.

currency: Currency
description: string

A description of the goods being sold.

deposit_price: integer (int64)
deposit_charge: integer (int64)
charge_calculator_version: integer (int64)
skip_remainder: boolean

If skip_remainder is true then the transaction will move to the "confirm handover" step after the deposit has been accepted.

Request Content-Types: application/json
Request Example
{
  "join_user_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "creator_role": "seller",
  "currency": "eur",
  "description": "Soccer ticket",
  "deposit_price": 1234,
  "deposit_charge": 78,
  "charge_calculator_version": 2
}
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

  • duplicate_user_id: The user specified by join_user_id is the user making the request.
  • incorrect_calc_version
  • incorrect_charge
  • invalid_calc_version
  • negative_price
  • price_too_low
Response Content-Types: application/json
Response Example (201 Created)
{
  "id": 1309,
  "status": "created",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

F2F Single-use Listings

Create a new single-use, face-to-face listing for the logged-in user

POST /p2p/me/single_use_listings/create

Single-use listings are disabled once the remainder has been paid for a transaction created from it.

role: Role
description: string

A description of the goods being sold.

currency: Currency
deposit_price: integer (int64)

The deposit price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

deposit_charge: integer (int64)

The charge value returned from a request to /p2p/charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /p2p/charge.

skip_remainder: boolean

If skip_remainder is true then the transaction will move to the "confirm handover" step after the deposit has been accepted.

Request Content-Types: application/json
Request Example
{
  "role": "seller",
  "currency": "eur",
  "description": "Soccer ticket",
  "deposit_price": 1234,
  "deposit_charge": 78,
  "charge_calculator_version": 5
}
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

* `invalid_role`: '' is not a valid role
Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Soccer ticket",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "skip_remainder": false,
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z"
}

Create a new single-use, face-to-face listing for the logged-in user

POST /p2p/me/single_use_listings

DEPRECATED

Single-use-listings for F2F transactions should be created using /p2p/me/single_use_listings/create.

Single-use listings are disabled once the remainder has been paid for a transaction created from it.

201 Created

Created

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "",
  "skip_remainder": false,
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z"
}

Get a listing by its ID

GET /p2p/single_use_listings/{listingId}
listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "",
  "skip_remainder": false,
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z"
}

Delete this listing

DELETE /p2p/single_use_listings/{listingId}
listingId

(no description)

type
integer (int64)
in
path
204 No Content

OK

404 Not Found

Not Found

Response Content-Types: application/json

Set the description for this listing

POST /p2p/single_use_listings/{listingId}/set_description
description: string
listingId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "description": "Soccer ticket"
}
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z"
}

Set pricing for this listing

POST /p2p/single_use_listings/{listingId}/set_deposit_pricing
currency: Currency
deposit_price: integer (int64)

The deposit price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

deposit_charge: integer (int64)

The charge value returned from a request to /p2p/charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /p2p/charge.

listingId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "currency": "eur",
  "deposit_price": 1234,
  "deposit_charge": 78,
  "charge_calculator_version": 5
}
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "skip_remainder": false,
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z"
}

Create a transaction from this listing

POST /p2p/single_use_listings/{listingId}/create_transaction
listingId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • listing_is_disabled
  • is_listing_creator: The current user created this listing.
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "joined",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Disable this listing

POST /p2p/single_use_listings/{listingId}/disable

Calling /create_transaction on a disabled listing will return a 400 response.

listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z",
  "disabled": "2019-12-25T10:00:00.000Z"
}

Enable this listing

POST /p2p/single_use_listings/{listingId}/enable
listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z"
}

F2F Multi-use Listings

Create a new multi-use, face-to-face listing for the logged-in user

POST /p2p/me/multi_use_listings/create

Multi-use listings can be used to create transactions.

role: Role
description: string

A description of the goods being sold.

currency: Currency
deposit_price: integer (int64)

The price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

deposit_charge: integer (int64)

The charge value returned from a request to /p2p/charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /p2p/charge.

skip_remainder: boolean

If skip_remainder is true then the transaction will move to the "confirm handover" step after the deposit has been accepted.

Request Content-Types: application/json
Request Example
{
  "role": "seller",
  "currency": "eur",
  "description": "Soccer ticket",
  "deposit_price": 1234,
  "deposit_charge": 78,
  "charge_calculator_version": 5
}
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

* `invalid_role`: '' is not a valid role
Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Soccer ticket",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "skip_remainder": false,
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z"
}

Create a new multi-use, face-to-face listing for the logged-in user

POST /p2p/me/multi_use_listings

DEPRECATED

Multi-use-listings for online transactions should be created using /p2p/me/multi_use_listings/create.

Multi-use listings can be used to create transactions.

201 Created

Created

Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "",
  "skip_remainder": false,
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z"
}

Get a listing by its ID

GET /p2p/multi_use_listings/{listingId}
listingId

(no description)

type
integer (int64)
in
path

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "",
  "skip_remainder": false,
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z"
}

Delete this listing

DELETE /p2p/multi_use_listings/{listingId}
listingId

(no description)

type
integer (int64)
in
path
204 No Content

OK

404 Not Found

Not Found

Response Content-Types: application/json

Set the description for this listing

POST /p2p/multi_use_listings/{listingId}/set_description
description: string
listingId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "description": "Soccer ticket"
}

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z"
}

Set pricing for this listing

POST /p2p/multi_use_listings/{listingId}/set_deposit_pricing
currency: Currency
deposit_price: integer (int64)

The deposit price of the goods being sold, in the currency's smallest unit. The charge value should correspond to the Trustap charge created with this price, otherwise this request will fail with a 400 error.

deposit_charge: integer (int64)

The charge value returned from a request to /p2p/charge.

charge_calculator_version: integer (int64)

The charge_calculator_version value returned from a request to /p2p/charge.

listingId

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "currency": "eur",
  "deposit_price": 1234,
  "deposit_charge": 78,
  "charge_calculator_version": 5
}

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "pricing": {
    "price": 1234,
    "charge": 78
  },
  "skip_remainder": false,
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z"
}

Create a transaction from this listing

POST /p2p/multi_use_listings/{listingId}/create_transaction
listingId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • listing_is_disabled
  • is_listing_creator: The current user created this listing.
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1309,
  "status": "joined",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Disable this listing

POST /p2p/multi_use_listings/{listingId}/disable

Calling /create_transaction on a disabled listing will return a 400 response.

listingId

(no description)

type
integer (int64)
in
path

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z",
  "disabled": "2019-12-25T10:00:00.000Z"
}

Enable this listing

POST /p2p/multi_use_listings/{listingId}/enable
listingId

(no description)

type
integer (int64)
in
path

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z"
}

Notifications

Get notifications for the logged-in user

GET /me/notifications
after_id

Only return notifications that were created chronologically after the notification with this ID (i.e. with smaller IDs)

type
integer (int64) , { x ∈ ℤ | x ≥ 0 }
in
query
limit

The maximum number of notifications to return

type
integer (int64) , { x ∈ ℤ | 1 ≤ x ≤ 50 } 25
in
query
200 OK

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_after_id
  • invalid_limit
Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": 1990,
    "created": "2019-12-25T10:00:00.000Z",
    "user_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
    "description": "Buyer has joined transaction for 'Soccer ticket'",
    "target": "basic/1309"
  }
]
Response Example (400 Bad Request)
{
  "code": "invalid_after_id",
  "error": "invalid after id"
}

Get a notification by its ID

GET /notifications/{notificationId}
notificationId

(no description)

type
integer (int64)
in
path
200 OK

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1990,
  "created": "2019-12-25T10:00:00.000Z",
  "user_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Buyer has joined transaction for 'Soccer ticket'",
  "target": "basic/1309"
}

Mark this notification as read

GET /notifications/{notificationId}/mark_as_read
notificationId

(no description)

type
integer (int64)
in
path
200 OK

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "id": 1990,
  "created": "2019-12-25T10:00:00.000Z",
  "read": "2019-12-25T11:00:00.000Z",
  "user_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Buyer has joined transaction for 'Soccer ticket'",
  "target": "basic/1309"
}

Schema Definitions

Carrier: object

code: string
name: string
Example
{
  "code": "string",
  "name": "string"
}

CarrierName: string , x ∈ { fedex , ups , usps }

Example
"fedex"

Charge: object

currency: string
charge: integer (int64)

The Trustap fee, in the currency's smallest unit, for a queried amount. See the Stripe documentation for more details.

charge_calculator_version: integer (int64)

The version of the Trustap charge calculator that was used to calculate this charge.

Example
{
  "currency": "eur",
  "charge": 78,
  "charge_calculator_version": 5
}

Currency: string , x ∈ { eur , gbp , usd }

Example
"eur"

Error: object

code: string
error: string

A contextual description of the error that occurred. When handling errors the code field should be used to determine the type of error that occurred, as the text in the error field may change unexpectedly.

Example
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

BuyerDetails: object

email: string
name: object
phone: string
Example
{
  "email": "string",
  "name": {
    "first": "string",
    "last": "string"
  },
  "phone": "string"
}

Role: string , x ∈ { buyer , seller }

Example
"buyer"

Pricing: object

price: integer (int64)
charge: integer (int64)
Example
{
  "price": 1234,
  "charge": 78
}

BasicSingleUseListing: object

id: integer (int64)
creator_id: string
creator_role: string
currency: string
pricing: Pricing
description: string
disabled: string
created: string
Example
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "created": "2019-12-25T09:00:00.000Z"
}

BasicMultiUseListing: object

id: integer (int64)
creator_id: string
creator_role: string
currency: string
pricing: Pricing
description: string
disabled: string
created: string
Example
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "created": "2019-12-25T09:00:00.000Z"
}

P2PSingleUseListing: object

id: integer (int64)
creator_id: string
creator_role: string
currency: string
deposit_pricing: Pricing
description: string
skip_remainder: boolean
allows_multi_use: boolean
created: string
disabled: string
Example
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "",
  "skip_remainder": false,
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z"
}

P2PMultiUseListing: object

id: integer (int64)
creator_id: string
creator_role: string
currency: string
deposit_pricing: Pricing
description: string
skip_remainder: boolean
allows_multi_use: boolean
created: string
Example
{
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "deposit_pricing": {
    "price": 5000,
    "charge": 150
  },
  "description": "",
  "skip_remainder": false,
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z"
}

Notification: object

id: integer (int64)
created: string
read: string
user_id: string
description: string
target: string
Example
{
  "id": 1990,
  "created": "2019-12-25T10:00:00.000Z",
  "user_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Buyer has joined transaction for 'Soccer ticket'",
  "target": "basic/1309"
}

BasicTransaction: object

id: integer (int64)
listing_id: string
currency: string

The currency of the transaction. Note that, at present, the buyer must pay using the transaction's currency and the seller will be paid in the transaction's currency.

price: integer (int64)
charge: integer (int64)
description: string
created: string
buyer_id: integer (int64)
seller_id: integer (int64)
joined: string
accepted_by_listing_creator: string
rejected_by_listing_creator: string
denied: string
paid: string
tracked: string
delivered: string
complained: string
complaint: string
funds_released: string
join_code: string
Example
{
  "id": 1309,
  "status": "funds_released",
  "currency": "eur",
  "price": 1234,
  "charge": 78,
  "description": "Soccer ticket",
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  },
  "delivered": "2019-12-25T13:00:00.000Z",
  "funds_released": "2019-12-26T14:00:00.000Z"
}

P2PTransaction: object

id: integer (int64)
listing_id: string
currency: string

The currency of the transaction. Note that, at present, the buyer must pay using the transaction's currency and the seller will be paid in the transaction's currency.

deposit_pricing: Pricing
description: string
skip_remainder: boolean

If skip_remainder is true then this transaction will move to the "confirm handover" step after the deposit has been accepted.

created: string
buyer_id: integer (int64)
seller_id: integer (int64)
joined: string
rejected: string
cancelled: string
deposit_paid: string
deposit_accepted: string
priced: string
pricing: Pricing
remainder_paid: string
buyer_handover_confirmed: string
seller_handover_confirmed: string
funds_released: string
complaint: string
complained: string
Example
{
  "id": 1309,
  "status": "funds_released",
  "currency": "eur",
  "deposit_pricing": {
    "price": 1234,
    "charge": 78
  },
  "description": "Soccer ticket",
  "skip_remainder": false,
  "created": "2019-12-25T09:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "joined": "2019-12-25T10:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_accepted": "2019-12-25T12:00:00.000Z",
  "pricing": {
    "price": 5000,
    "charge": 190
  },
  "priced": "2019-12-25T13:00:00.000Z",
  "remainder_paid": "2019-12-25T14:00:00.000Z",
  "seller_handover_confirmed": "2019-12-25T15:00:00.000Z",
  "buyer_handover_confirmed": "2019-12-25T16:00:00.000Z",
  "funds_released": "2019-12-25T17:00:00.000Z"
}