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

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

Online Transactions

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

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
quantity

When creating transactions from a multi-use listing, the quantity parameter can be provided in order to generate a charge for the given price multiplied by the given quantity. See /multi_use_listings/{listingId}/create_transaction for more details.

type
integer (int64)
in
query
payment_method

The payment method that will be used to pay for the transaction. This is necessary because different payment methods may result in different fees.

The default value is card.

type
string
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)
{
  "charge": 78,
  "charge_calculator_version": 5,
  "currency": "eur"
}
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.

before_id

Only return transactions that were created chronologically before the transaction with this ID

type
integer (int64) , { x ∈ ℤ | x ≥ 0 }
in
query
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_before_id
  • invalid_after_id
  • invalid_limit
Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "charge": 78,
    "charge_seller": 0,
    "created": "2019-12-25T09:00:00.000Z",
    "currency": "eur",
    "description": "Soccer ticket",
    "id": 1309,
    "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4",
    "price": 1234,
    "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
    "status": "created"
  },
  {
    "buyer_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
    "charge": 78,
    "charge_seller": 0,
    "created": "2018-12-25T09:00:00.000Z",
    "currency": "eur",
    "description": "Soccer ticket",
    "id": 609,
    "join_code": "c9cd6a9d-1096-4d38-b4aa-2c354beac845",
    "price": 1234,
    "status": "created"
  }
]
Response Example (400 Bad Request)
{
  "code": "invalid_after_id",
  "error": "invalid after id"
}

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.

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.

charge_seller: integer (int64)

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

client_id: string
currency: string

The currency that the price is specified in.

description: string

A description of the goods being sold.

features: string[]

features contains flags that modify the transaction flow. The following are the currently supported values:

  • require_seller_acceptance
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.

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

Created

400 Bad Request

Bad Request

code can be one of the following:

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

Create a new basic transaction with both users

POST /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 basic_tx:offline_create_join scope to the client that is performing the request.

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.

charge_seller: integer (int64)

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

client_id: string
creator_role: basic.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: string

The currency that the price is specified in.

description: string

A description of the goods being sold.

features: string[]

features contains flags that modify the transaction flow. The following are the currently supported values:

  • require_seller_acceptance
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.

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.

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

Created

400 Bad Request

Bad Request

code can be one of the following:

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

Create a new online transaction with both users

POST /me/transactions/create_with_guest_user

This endpoint is an optimised call that allows a transaction to be created and joined in a single request. It requires the online user to have granted the basic_tx:offline_create_join scope to the client that is performing the request. This endpoint allows creating a transaction with both buyer and seller as guest or full users, or one party to be guest user and the other full user.

buyer_id: string

The id of the buyer for this transaction (it can be full user id or guest user id).

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.

client_id: string
creator_role: basic.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.

features: string[]

features contains flags that modify the transaction flow. The following are the currently supported values:

  • require_seller_acceptance
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.

seller_id: string

The id of the seller for this transaction (it can be full user id or guest user id).

Request Content-Types: application/json
Request Example
[
  {
    "buyer_id": "1-bd5bb99j-95bf-87e2-ce0d-95e7541c6ad5",
    "charge": 78,
    "charge_seller": 0,
    "created": "2019-12-25T09:00:00.000Z",
    "creator_role": "buyer",
    "currency": "eur",
    "description": "Soccer ticket",
    "id": 1309,
    "joined": "2019-12-25T09:00:00.000Z",
    "price": 1234,
    "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
    "status": "joined"
  }
]
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

  • incorrect_calc_version
  • incorrect_charge
  • incorrect_charge_seller
  • invalid_calc_version
  • negative_price
  • price_too_low
  • incompatible_countries
  • unsupported_currency
  • invalid_role
  • no_guest_user
Response Content-Types: application/json
Response Example (201 Created)
{
  "buyer_id": "bd5bb99f-85bf-47e1-be0d-15e7541c6ad9",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T09:01:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "joined"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

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 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)
{
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "created"
}
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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "joined"
}
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/{join_code}/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.

join_code

(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)
{
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "denied": "2019-12-25T10:00:00.000Z",
  "description": "Soccer ticket",
  "id": 1309,
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "rejected"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Get a transaction by its ID

GET /transactions/{transaction_id}
transaction_id

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

Updates description, currency, price and/or charge of transaction

PATCH /transactions/{transaction_id}
charge: integer (int64)

The charge value returned from a request to /charge.

charge_seller: integer (int64)

The charge_seller value returned from a request to /charge.

currency: string
description: string

A description of the goods being sold.

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.

transaction_id

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "charge": 78,
  "currency": "eur",
  "description": "Soccer ticket",
  "price": 1234
}

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_id
  • second_party_already_joined
  • values_not_changed
403 Forbidden

Forbidden

404 Not Found

Not Found

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

Allow this listing-based transaction to proceed

POST /transactions/{transaction_id}/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. Offline access is allowed for this endpoint when the user has granted the basic_ls:offline_accept_listing scope to the client that is performing the request.

transaction_id

(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)
{
  "accepted_by_listing_creator": "2019-12-25T11:00:00.000Z",
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "listing_id": 1990,
  "listing_type": "single_use",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "paid"
}
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"
}

This endpoint lets the seller accept payment and is accessible only if the seller has granted a feature require_seller_acceptance.

POST /transactions/{transaction_id}/accept_payment

Offline access is allowed for this endpoint when the user has granted the basic_tx:offline_accept_payment scope to the client that is performing the request.

transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • missing_required_feature
  • payment_already_accepted
  • transaction_not_paid_yet
404 Not Found

Not Found

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

This endpoint allows payment acceptance for the seller specified in the header as Trustap-User.

POST /transactions/{transaction_id}/accept_payment_with_guest_seller
transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • missing_required_feature
  • payment_already_accepted
  • transaction_not_paid_yet
404 Not Found

Not Found

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

Get details of the buyer from this transaction

GET /transactions/{transaction_id}/buyer_details
transaction_id

(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": "John",
    "last": "Doe"
  },
  "phone": "string"
}

Cancel this transaction

POST /transactions/{transaction_id}/cancel

Transaction can be cancelled until it's paid or if the feature RequireSellerAcceptance is present, it can be cancelled until it's tracked. Offline access is allowed for this endpoint when the user has granted the basic_tx:offline_cancel scope to the client that is performing the request.

transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_id
  • already_paid
  • already_cancelled
  • tracking_already_added
403 Forbidden

Forbidden

404 Not Found

Not Found

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

Cancel this transaction with a guest user

POST /transactions/{transaction_id}/cancel_with_guest_user

This endpoint cancels a transaction for the user specified in the header as Trustap-User. Transaction can be cancelled until it's paid or if the feature RequireSellerAcceptance is present, it can be cancelled until it's tracked.

transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_id
  • already_paid
  • already_cancelled
  • tracking_already_added
403 Forbidden

Forbidden

404 Not Found

Not Found

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

Get the Trustap fee for a transaction

GET /transactions/{transaction_id}/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.

transaction_id

(no description)

type
integer (int64)
in
path
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
quantity

When creating transactions from a multi-use listing, the quantity parameter can be provided in order to generate a charge for the given price multiplied by the given quantity. See /multi_use_listings/{listingId}/create_transaction for more details.

type
integer (int64)
in
query
payment_method

The payment method that will be used to pay for the transaction. This is necessary because different payment methods may result in different fees.

The default value is card.

type
string
in
query
200 OK

OK

400 Bad Request

Bad Request

code can be one of the following:

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

This endpoint allows a client's claim transactions for sellers on behalf of the buyer. It requires to have granted the basic_tx:offline_claim scope and API Key authentication. The endpoint is not accessible for guests and full users.

POST /transactions/{transaction_id}/claim_for_buyer
transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • already_claimed
  • cannot_claim_own_transaction
404 Not Found

Not Found

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

This endpoint allows a client's claim transactions for sellers on behalf of the seller. It requires to have granted the basic_tx:offline_claim scope and API Key authentication. The endpoint is not accessible for guests and full users.

POST /transactions/{transaction_id}/claim_for_seller
transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • already_claimed
  • cannot_claim_own_transaction
404 Not Found

Not Found

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

Flag a complaint for this transaction

POST /transactions/{transaction_id}/complain

DEPRECATED

Complaints should be submitted using /transactions/{transaction_id}/complain_with_description. Offline access is allowed for this endpoint when the user has granted the basic_tx:offline_complain scope to the client that is performing the request.

transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • already_complained
  • unconfirmed_delivery: The complaint period for this transaction has not yet started.
  • complaint_period_ended_prematurely: The buyer has already ended the complaint period.
  • complaint_period_expired
  • funds_already_released
  • invalid_id
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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "complained": "2019-12-25T14:00:00.000Z",
  "complaint": {
    "description": ""
  },
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "delivered": "2019-12-25T13:00:00.000Z",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "complained",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}
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"
}

Submit a detailed complaint for this transaction

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

(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:

  • empty_complaint_description
  • already_complained
  • unconfirmed_delivery: The complaint period for this transaction has not yet started.
  • complaint_period_ended_prematurely: The buyer has already ended the complaint period.
  • complaint_period_expired
  • funds_already_released
  • invalid_id
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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "complained": "2019-12-25T14:00:00.000Z",
  "complaint": {
    "description": "Item was fake"
  },
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "delivered": "2019-12-25T13:00:00.000Z",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "complained",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}
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"
}

Submit a detailed complaint for this transaction for the guest buyer specified in the header as Trustap-User.

POST /transactions/{transaction_id}/complain_with_guest_buyer
description: string
transaction_id

(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:

  • empty_complaint_description
  • already_complained
  • unconfirmed_delivery: The complaint period for this transaction has not yet started.
  • complaint_period_ended_prematurely: The buyer has already ended the complaint period.
  • complaint_period_expired
  • funds_already_released
  • invalid_id
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)
{
  "buyer_id": "1-feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "complained": "2019-12-25T14:00:00.000Z",
  "complaint": {
    "description": "Item was fake"
  },
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "delivered": "2019-12-25T13:00:00.000Z",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "complained",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}
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"
}

Confirm delivery for this transaction

POST /transactions/{transaction_id}/confirm_delivery

This endpoint allows the buyer to manually confirm the delivery of the item in the case that the state of the transaction was not updated asynchronously by Trustap.

transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • tracking_not_added
  • delivery_already_set
  • invalid_id
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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "delivered": "2019-12-26T12:00:00.000Z",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "delivered",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}
Response Example (400 Bad Request)
{
  "code": "delivery_already_set",
  "error": "delivery details already added"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Confirm delivery for this transaction

POST /transactions/{transaction_id}/confirm_delivery_with_guest_buyer

This endpoint allows the client to manually confirm the delivery on behalf of the guest buyer specified in the header as Trustap-User.

transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • tracking_not_added
  • delivery_already_set
  • invalid_id
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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "delivered": "2019-12-26T12:00:00.000Z",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "1-ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "delivered",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}
Response Example (400 Bad Request)
{
  "code": "delivery_already_set",
  "error": "delivery details already added"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

End the complaint period for this transaction

POST /transactions/{transaction_id}/end_complaint_period
transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • complaint_period_expired
  • already_complained
  • complaint_period_ended_prematurely
  • 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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "complaint_period_ended": "2019-12-25T14:00:00.000Z",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "delivered": "2019-12-25T13:00:00.000Z",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "complaint_period_ended",
  "tracked": "2019-12-25T12:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}
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"
}

Extend tracking details submission deadline for this transaction

POST /transactions/{transaction_id}/extend_tracking_deadline

This endpoint allows the buyer to extend the tracking details submission deadline for the seller.

transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_id
  • tracking_already_added
  • payment_details_not_added
  • tracking_submission_window_not_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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "paid",
  "tracking_details_window_start": "2019-12-25T12:00:00.000Z"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Set payment details and process payment for this transaction

POST /transactions/{transaction_id}/pay

DEPRECATED

Payment should be processed using the asynchronous payment flow (see /transactions/{transaction_id}/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.

transaction_id

(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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "paid"
}
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"
}

Cancel this listing-based transaction

POST /transactions/{transaction_id}/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.

transaction_id

(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
  • second_party_not_joined
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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "listing_id": 1990,
  "listing_type": "single_use",
  "price": 1234,
  "rejected_by_listing_creator": "2019-12-25T11:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "paid"
}
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"
}

Get details of the seller from this transaction

GET /transactions/{transaction_id}/seller_details
transaction_id

(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": "John",
    "last": "Doe"
  },
  "phone": "string"
}

Set the payment method to be used for this transaction

POST /transactions/{transaction_id}/set_payment_method

Different payment methods incur different rates, so the payment method to be used for a transaction must be set before the payment is made. This requires retrieving the charge associated with the payment method using GET /transactions/{transaction_id}/charge, and passing the generated charge as a parameter to this endpoint.

charge: integer (int64)

The charge value returned from a request to /charge.

charge_seller: integer (int64)

The charge_seller value returned from a request to /charge.

currency: string
payment_method: string
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.

transaction_id

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "charge": "integer (int64)",
  "charge_seller": "integer (int64)",
  "currency": "string",
  "payment_method": "string",
  "price": "integer (int64)"
}

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_payment_method
  • unsupported_currency
  • currency_missing
  • incorrect_charge
  • incorrect_charge_seller
  • incorrect_price
  • incorrect_currency
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)
{
  "charge": 78,
  "charge_seller": 0,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "created"
}
Response Example (400 Bad Request)
{
  "code": "incorrect_price",
  "error": "specified price doesn't match expected price"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Get shipping details of the buyer from this transaction

GET /transactions/{transaction_id}/shipping_details
transaction_id

(no description)

type
integer (int64)
in
path

OK

404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "address": {
    "city": "string",
    "country": "string",
    "line1": "string",
    "line2": "string",
    "postal_code": "string",
    "state": "string"
  },
  "name": "string",
  "phone": "string"
}

Post shipping details of the buyer from this transaction

POST /transactions/{transaction_id}/shipping_details
address_line_1: string
address_line_2: string
city: string
country: string
name: string
phone: string
postal_code: string
state: string
transaction_id

(no description)

type
integer (int64)
in
path
Request Content-Types: application/json
Request Example
{
  "address_line_1": "3672 Massillon Rd",
  "address_line_2": "3672 Massillon Rd",
  "city": "Green",
  "country": "us",
  "name": "John Doe",
  "phone": "330-896-9303",
  "postal_code": 44685,
  "state": "Ohio"
}

OK

400 Bad Request

Bad Request

code can be one of the following:

  • empty_name
  • empty_phone
  • empty_city
  • empty_postal_code
  • empty_state
  • empty_line_1
  • empty_country
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "address": {
    "city": "string",
    "country": "string",
    "line1": "string",
    "line2": "string",
    "postal_code": "string",
    "state": "string"
  },
  "name": "string",
  "phone": "string"
}

Get the Stripe client secret for this transaction

GET /transactions/{transaction_id}/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.

transaction_id

(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"
}

Get the details for the Stripe publishable key that is in use for this transaction

GET /transactions/{transaction_id}/stripe_publishable_key

Returns the Publishable Key for the Stripe Platform which is hosting this transaction.

transaction_id

(no description)

type
integer (int64)
in
path
200 OK

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_id
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
  • not_seller
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "publishable_key": "pk_xXxXxXxXxXx"
}
Response Example (400 Bad Request)
{
  "code": "invalid_id",
  "error": "couldn't parse transaction id: abc"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

Set postal tracking details for this transaction

POST /transactions/{transaction_id}/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. Offline access is allowed for this endpoint when the user has granted the basic_tx:offline_track scope to the client that is performing the request.

carrier: string
tracking_code: string
transaction_id

(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:

  • invalid_id
  • empty_carrier
  • empty_tracking_code
  • tracking_already_added
  • payment_details_not_added
  • tracking_details_deadline_expired
  • already_cancelled
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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "tracked",
  "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"
}

Set postal tracking details for this transaction

POST /transactions/{transaction_id}/track_with_guest_seller

Add tracking details for the guest seller specified in the header as Trustap-User.

carrier: string
tracking_code: string
transaction_id

(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:

  • invalid_id
  • empty_carrier
  • empty_tracking_code
  • tracking_already_added
  • payment_details_not_added
  • tracking_details_deadline_expired
  • already_cancelled
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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "paid": "2019-12-25T11:00:00.000Z",
  "price": 1234,
  "seller_id": "1-ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "tracked",
  "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"
}

This endpoint allows a full user to claim for a transaction as buyer given a claim secret.

POST /transactions_by_claim_secret/{secret}/claim_as_buyer
secret

(no description)

type
string
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • already_claimed
  • cannot_claim_own_transaction
  • missing_secret
404 Not Found

Not Found

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

Users

Create a new guest user

POST /guest_users

This endpoint creates guest user which can be used as the buyer or the seller. If guest user is used as the seller in a transaction, they need to be created with country_code parameter correctly set. This is important because of currencies they can use in their transactions. tos_acceptance is the parameter which is important for disputes/chargeback and represent the timestamp when Trustap ToS were accepted https://www.trustap.com/terms.

country_code: string
email: string
first_name: string
last_name: string
tos_acceptance: users.TosAcceptance
Request Content-Types: application/json
Request Example
{
  "country_code": "IE",
  "email": "guest@test.com",
  "first_name": "Test",
  "last_name": "User",
  "tos_acceptance": {
    "ip": "192.168.1.2",
    "unix_timestamp": 1672531200
  }
}
201 Created

Created

400 Bad Request

Bad Request code can be one of the following:

* `email_missing`
* `first_name_missing`
* `last_name_missing`
* `tos_acceptance_ip_missing`
* `invalid_country_code`
* `invalid_email`
* `invalid_tos_acceptance_date`
Response Content-Types: application/json
Response Example (201 Created)
{
  "id": "1-feb33a87-3917-4538-9260-127c8a6b5232"
}

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. Offline access is allowed for this endpoint when the user has granted the basic_ls:offline_create scope to the client that is performing the request.

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.

charge_seller: integer (int64)

The charge_seller value returned from a request to /charge.

currency: Currency
description: string

A description of the goods being sold.

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.

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

Created

400 Bad Request

Bad Request

code can be one of the following:

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

Delete this listing

DELETE /multi_use_listings/{listing_id}
listing_id

(no description)

type
string
in
path
204 No Content

No Content

404 Not Found

Not Found

Response Content-Types: application/json

Get a listing by its ID

GET /multi_use_listings/{listing_id}
listing_id

(no description)

type
string
in
path
404 Not Found

Not Found

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

Patch listing properties

PATCH /multi_use_listings/{listing_id}
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.

charge_seller: integer (int64)

The charge_seller value returned from a request to /charge.

currency: Currency
description: string
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.

listing_id

(no description)

type
string
in
path
Request Content-Types: application/json
Request Example
{
  "charge": 78,
  "charge_calculator_version": 5,
  "currency": "eur",
  "description": "Soccer ticket",
  "price": 1234
}
400 Bad Request

Bad Request

code can be one of the following:

  • empty_body: The request body is empty.
  • partial_pricing: When updating a pricing field, all 3 of currency, price and charge must be supplied.
404 Not Found

Not Found

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

Create a transaction from this listing

POST /multi_use_listings/{listing_id}/create_transaction

Calling /create_transaction with no parameters will create a new transaction with the details provided by the listing.

The optional quantity parameter can be passed to create a transaction for a multiple of the original listing. In this case, the price and charge for the new transaction will also need to be passed.

As an example, consider a listing for a chair with a price of 1234 EUR. If a user wants to buy 10 of these in a single transaction then the charge for the total can be retrieved using GET /charge?price=1234&currency=usd&quantity=10 (note the addition of the optional quantity parameter at the end). This will return a price of 12340 and an associated charge. These new values must then be passed to /create_transaction with quantity=10, which will create a new transaction with the new pricing information. The new transaction will also include a quantity field, which doesn't have a functional effect on the transaction, but is included for informational purposes.

Note that this functionality is not available for single-use listings, from which only singular transactions may be created.

listing_id

(no description)

type
string
in
path
quantity

(no description)

type
integer (int64)
in
query
price

(no description)

type
integer (int64)
in
query
charge

(no description)

type
integer (int64)
in
query
payment_method

(no description)

type
string
in
query
201 Created

Created

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 (201 Created)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "charge_seller": 0,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "listing_id": 1990,
  "listing_type": "multi_use",
  "price": 1234,
  "quantity": 10,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "joined"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Create a transaction from this listing

POST /multi_use_listings/{listing_id}/create_transaction_with_guest_buyer
listing_id

(no description)

type
string
in
path
201 Created

Created

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 (201 Created)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "charge_seller": 0,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "listing_id": 1990,
  "listing_type": "multi_use",
  "price": 1234,
  "quantity": 10,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "joined"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Disable this listing

POST /multi_use_listings/{listing_id}/disable

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

listing_id

(no description)

type
string
in
path
404 Not Found

Not found

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

Enable this listing

POST /multi_use_listings/{listing_id}/enable
listing_id

(no description)

type
string
in
path
404 Not Found

Not found

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

Set description for this listing

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

(no description)

type
string
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)
{
  "created": "2019-12-25T09:00:00.000Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Soccer ticket",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a"
}

Set pricing for this listing

POST /multi_use_listings/{listing_id}/set_pricing
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.

charge_seller: integer (int64)

The charge_seller value returned from a request to /charge.

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.

listing_id

(no description)

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

Not Found

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

Notifications

Get notifications for the logged-in user

GET /me/notifications
before_id

Only return transactions that were created chronologically before the transaction with this ID

type
integer (int64) , { x ∈ ℤ | x ≥ 0 }
in
query
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
400 Bad Request

Bad Request

code can be one of the following:

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

Get a notification by its ID

GET /notifications/{notification_id}
notification_id

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

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

Mark this notification as read

POST /notifications/{notification_id}/mark_as_read
notification_id

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

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

Personal

Get verification status for the front side of the secondary identity document

GET /me/personal/additional_identity_document/verification_status
Response Content-Types: application/json
Response Example (200 OK)
{
  "previously_submitted": true,
  "status": "verifying"
}

Get verification status for the back side of the secondary identity document

GET /me/personal/additional_identity_document_back/verification_status
Response Content-Types: application/json
Response Example (200 OK)
{
  "previously_submitted": true,
  "status": "verifying"
}

Get verification status for the front side of the primary identity document

GET /me/personal/identity_document/verification_status
Response Content-Types: application/json
Response Example (200 OK)
{
  "previously_submitted": true,
  "status": "verifying"
}

Get verification status for the back side of the primary identity document

GET /me/personal/identity_document_back/verification_status
Response Content-Types: application/json
Response Example (200 OK)
{
  "previously_submitted": true,
  "status": "verifying"
}

Get the details for the Stripe publishable key the user is linked to.

GET /me/personal/stripe_publishable_key

Returns the Publishable Key for the Stripe Platform which the user is linked to.

200 OK

OK

Response Content-Types: application/json
Response Example (200 OK)
{
  "publishable_key": "pk_xXxXxXxXxXx"
}

Get the status of a user's ability to accept payouts. This endpoint requires the user identified by the Trustap-User header to have granted the profile scope to the client that is performing the request.

GET /me/profile/payout_status

Offline access is allowed for this endpoint when the user has granted the profile scope to the client that is performing the request.

Response Content-Types: application/json
Response Example (200 OK)
{
  "status": "verifying"
}

Online Single-use Listings

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.

Created

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

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. Offline access is allowed for this endpoint when the user has granted the basic_ls:offline_create scope to the client that is performing the request.

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.

charge_seller: integer (int64)

The charge_seller value returned from a request to /charge.

currency: Currency
description: string

A description of the goods being sold.

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.

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

Created

400 Bad Request

Bad Request

code can be one of the following:

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

Delete this listing

DELETE /single_use_listings/{listing_id}
listing_id

(no description)

type
string
in
path
204 No Content

No Content

404 Not Found

Not Found

Response Content-Types: application/json

Get a listing by its ID

GET /single_use_listings/{listing_id}
listing_id

(no description)

type
string
in
path
404 Not Found

Not Found

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

Patch listing properties

PATCH /single_use_listings/{listing_id}
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.

charge_seller: integer (int64)

The charge_seller value returned from a request to /charge.

currency: Currency
description: string
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.

listing_id

(no description)

type
string
in
path
Request Content-Types: application/json
Request Example
{
  "charge": 78,
  "charge_calculator_version": 5,
  "currency": "eur",
  "description": "Soccer ticket",
  "price": 1234
}
400 Bad Request

Bad Request

code can be one of the following:

  • empty_body: The request body is empty.
  • partial_pricing: When updating a pricing field, all 3 of currency, price and charge must be supplied.
404 Not Found

Not Found

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

Create a transaction from this listing

POST /single_use_listings/{listing_id}/create_transaction
listing_id

(no description)

type
string
in
path
201 Created

Created

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 (201 Created)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "listing_id": 1990,
  "listing_type": "single_use",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "joined"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Create a transaction from this listing

POST /single_use_listings/{listing_id}/create_transaction_with_guest_buyer
listing_id

(no description)

type
string
in
path
201 Created

Created

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 (201 Created)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "listing_id": 1990,
  "listing_type": "single_use",
  "price": 1234,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "joined"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Disable this listing

POST /single_use_listings/{listing_id}/disable

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

listing_id

(no description)

type
string
in
path
404 Not Found

Not found

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

Enable this listing

POST /single_use_listings/{listing_id}/enable
listing_id

(no description)

type
string
in
path
404 Not Found

Not found

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

Set description for this listing

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

(no description)

type
string
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)
{
  "created": "2019-12-25T09:00:00.000Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "description": "Soccer ticket",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a"
}

Set pricing for this listing

POST /single_use_listings/{listing_id}/set_pricing
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.

charge_seller: integer (int64)

The charge_seller value returned from a request to /charge.

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.

listing_id

(no description)

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

Not Found

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

F2F Transactions

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

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
fee_multiplier

The fee_multiplier parameter is used to apply a higher percentage fee based on the total price of the transaction. The percentage fee is calculated multiplying the percentage fee by the fee_multiplier.

type
number (double)
in
query
quantity

When creating transactions from a multi-use listing, the quantity parameter can be provided in order to generate a charge for the given price multiplied by the given quantity. See /p2p/multi_use_listings/{listingId}/create_transaction for more details.

type
integer (int64)
in
query
payment_method

The payment method that will be used to pay for the transaction. This is necessary because different payment methods may result in different fees.

The default value is card.

type
string
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)
{
  "charge": 78,
  "charge_calculator_version": 2,
  "currency": "eur"
}
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.

before_id

Only return transactions that were created chronologically before the transaction with this ID

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

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. Offline access is allowed for this endpoint when the user has granted the p2p_tx:offline_create_join scope to the client that is performing the request.

charge_calculator_version: integer (int64)
currency: Currency
deposit_charge: integer (int64)
deposit_price: integer (int64)
description: string

A description of the goods being sold.

role: basic.Role
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
{
  "charge_calculator_version": 2,
  "currency": "eur",
  "deposit_charge": 78,
  "deposit_price": 1234,
  "description": "Soccer ticket",
  "role": "seller"
}
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

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

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.

charge_calculator_version: integer (int64)
creator_role: basic.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
deposit_charge: integer (int64)
deposit_price: integer (int64)
description: string

A description of the goods being sold.

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.

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
{
  "charge_calculator_version": 2,
  "creator_role": "seller",
  "currency": "eur",
  "deposit_charge": 78,
  "deposit_price": 1234,
  "description": "Soccer ticket",
  "join_user_id": "feb33a87-3917-4538-9260-127c8a6b5232"
}
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
  • incorrect_charge_seller
  • invalid_calc_version
  • negative_price
  • price_too_low
Response Content-Types: application/json
Response Example (201 Created)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 78,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "joined"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

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

POST /p2p/me/transactions/create_with_guest_user

This endpoint is an optimised call that allows a transaction to be created and joined in a single request. It requires the online user to have granted the p2p_tx:offline_create_join scope to the client that is performing the request. This endpoint allows creating a transaction with both buyer and seller as guest users, or one party to be guest user and the other full user.

buyer_id: string

The id of the buyer for this transaction (it can be full user id or guest user id).

charge_calculator_version: integer (int64)
creator_role: basic.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
deposit_charge: integer (int64)
deposit_charge_seller: integer (int64)
deposit_price: integer (int64)
description: string

A description of the goods being sold.

fee_multiplier: number (double)

The fee_multiplier parameter is used to apply a higher percentage fee based on the total price of the transaction. The percentage fee is calculated multiplying the percentage fee by the fee_multiplier.

seller_id: string

The id of the seller for this transaction (it can be full user id or guest user id).

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
{
  "charge_calculator_version": 2,
  "creator_role": "seller",
  "currency": "eur",
  "deposit_charge": 78,
  "deposit_charge_seller": 0,
  "deposit_price": 1234,
  "description": "Soccer ticket",
  "join_user_id": "feb33a87-3917-4538-9260-127c8a6b5232"
}
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
  • incorrect_charge_seller
  • invalid_calc_version
  • negative_price
  • price_too_low
  • no_guest_user
  • incompatible_countries
  • unsupported_currency
  • fee_multiplier_too_low
Response Content-Types: application/json
Response Example (201 Created)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 78,
    "charge_seller": 0,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "joined"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Get a transaction by its ID

GET /p2p/transactions/{transaction_id}
transaction_id

(no description)

type
integer (int64)
in
path

OK

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

Updates description, currency, price and/or charge of F2F transaction

PATCH /p2p/transactions/{transaction_id}
currency: Currency
deposit_charge: integer (int64)
deposit_price: integer (int64)
description: string

A description of the goods being sold.

transaction_id

(no description)

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

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_id
  • second_party_already_joined
  • values_not_changed
403 Forbidden

Forbidden

404 Not Found

Not Found

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

End complaint period for this transaction with a guest buyer

POST /p2p/transactions/{transaction_id}/end_complaint_period_with_guest_buyer
transaction_id

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • complaint_period_expired
  • already_complained
  • handover_not_confirmed
  • funds_already_released
404 Not Found

Not Found

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

Accept the deposit for this transaction

POST /p2p/transactions/{transactionId}/accept_deposit

Offline access is allowed for this endpoint when the user has granted the p2p_tx:offline_accept_deposit scope to the client that is performing the request.

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

Accept the deposit for this transaction as a guest seller

POST /p2p/transactions/{transactionId}/accept_deposit_with_guest_seller
transactionId

(no description)

type
integer (int64)
in
path

OK

403 Forbidden

Forbidden

code can be one of the following:

  • not_seller
  • subject_is_not_guest_user
  • deposit_not_paid
  • deposit_already_accepted
404 Not Found

Not Found

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

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": "John",
    "last": "Doe"
  },
  "phone": "string"
}

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

400 Bad Request

Bad Request

code can be one of the following:

  • second_party_not_joined
  • already_cancelled
  • remainder_already_paid
  • handover_already_confirmed
404 Not Found

Not Found

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

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. Offline access is allowed for this endpoint when the user has granted the p2p_tx:offline_cancel scope to the client that is performing the request.

description: string
transactionId

(no description)

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

OK

400 Bad Request

Bad Request

code can be one of the following:

  • second_party_not_joined
  • already_cancelled
  • remainder_already_paid
  • handover_already_confirmed
404 Not Found

Not Found

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

Cancel this transaction with a description with guest user

POST /p2p/transactions/{transactionId}/cancel_with_description_with_guest_user

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

400 Bad Request

Bad Request

code can be one of the following:

  • description_missing
  • already_cancelled
  • remainder_already_paid
  • handover_already_confirmed
404 Not Found

Not Found

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

Submit a complaint for this transaction

POST /p2p/transactions/{transactionId}/complain

Offline access is allowed for this endpoint when the user has granted the p2p_tx:offline_complain scope to the client that is performing the request.

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:

  • remainder_required
  • already_complained
  • funds_already_released
  • complaint_period_expired
404 Not Found

Not Found

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

Submit a complaint for this transaction with a guest buyer

POST /p2p/transactions/{transactionId}/complain_with_guest_buyer
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:

  • remainder_required
  • already_complained
  • funds_already_released
  • complaint_period_expired
404 Not Found

Not Found

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

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. Offline access is allowed for this endpoint when the user has granted the p2p_tx:offline_confirm_handover scope to the client that is performing the request.

transactionId

(no description)

type
integer (int64)
in
path

OK

404 Not Found

Not Found

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

Confirm handover for this transaction with a guest user

POST /p2p/transactions/{transactionId}/confirm_handover_with_guest_user

Both parties should confirm the handover for a face-to-face transaction. Full users don't have access to this endpoint.

transactionId

(no description)

type
integer (int64)
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • remainder_required
  • already_complained
  • seller_handover_already_confirmed
  • buyer_handover_already_confirmed
404 Not Found

Not Found

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

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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_pricing": {
    "charge": 78,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "deposit_paid"
}
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 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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_accepted": "2019-12-25T12:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_pricing": {
    "charge": 78,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "priced": "2019-12-25T13:00:00.000Z",
  "pricing": {
    "charge": 190,
    "price": 5000
  },
  "remainder_paid": "2019-12-25T14:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "deposit_accepted"
}
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 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"
}

Get details of the seller from this transaction

GET /p2p/transactions/{transactionId}/seller_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": "John",
    "last": "Doe"
  },
  "phone": "string"
}

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. Offline access is allowed for this endpoint when the user has granted the p2p_tx:offline_set_price scope to the client that is performing the request.

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.

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.

transactionId

(no description)

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

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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_accepted": "2019-12-25T12:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_pricing": {
    "charge": 78,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "priced": "2019-12-25T13:00:00.000Z",
  "pricing": {
    "charge": 190,
    "price": 5000
  },
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "deposit_accepted"
}
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"
}

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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_accepted": "2019-12-25T12:00:00.000Z",
  "deposit_paid": "2019-12-25T11:00:00.000Z",
  "deposit_pricing": {
    "charge": 78,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "remainder_skipped": "2019-12-25T13:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "remainder_skipped"
}
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 details for the Stripe publishable key that is in use for this transaction

GET /p2p/transactions/{transactionId}/stripe_publishable_key

Returns the Publishable Key for the Stripe Platform which is hosting this transaction.

transactionId

(no description)

type
integer (int64)
in
path
200 OK

OK

400 Bad Request

Bad Request

code can be one of the following:

  • invalid_id
403 Forbidden

Forbidden

code can be one of the following:

  • not_buyer
  • not_seller
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "publishable_key": "pk_xXxXxXxXxXx"
}
Response Example (400 Bad Request)
{
  "code": "invalid_id",
  "error": "couldn't parse transaction id: abc"
}
Response Example (403 Forbidden)
{
  "code": "not_buyer",
  "error": "current user is not buyer"
}

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)
{
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 78,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": 1309,
  "join_code": "54c5bb89-a5ea-4be7-ad7a-e740c2eebab4",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "created"
}

Join a transaction by its join code

POST /p2p/transactions_by_join_code/{joinCode}/join

This endpoint allows a user to join a transaction provided a join code. Offline access is allowed for this endpoint when the user has granted the p2p_tx:offline_create_join scope to the client that is performing the request.

joinCode

(no description)

type
string
in
path

OK

400 Bad Request

Bad Request

code can be one of the following:

  • cannot_join_own_transaction
  • `already_cancelled``
404 Not Found

Not Found

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

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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 78,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": 1309,
  "rejected": "2019-12-25T10:00:00.000Z",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "joined"
}

F2F Multi-use Listings

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. Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_create scope to the client that is performing the request.

201 Created

Created

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

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. Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_create scope to the client that is performing the request.

charge_calculator_version: integer (int64)

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

charge_seller: integer (int64)

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

currency: Currency
deposit_charge: integer (int64)

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

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.

description: string

A description of the goods being sold.

role: basic.Role
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
{
  "charge_calculator_version": 5,
  "currency": "eur",
  "deposit_charge": 78,
  "deposit_price": 1234,
  "description": "Soccer ticket",
  "role": "seller"
}
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)
{
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 78,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "skip_remainder": false
}

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

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)
{
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 150,
    "price": 5000
  },
  "description": "",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "skip_remainder": false
}

Patch listing properties

PATCH /p2p/multi_use_listings/{listingId}
charge_calculator_version: integer (int64)

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

currency: Currency
deposit_charge: integer (int64)

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

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.

description: string
skip_remainder: boolean
listingId

(no description)

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

OK

400 Bad Request

Bad Request

code can be one of the following:

  • empty_body: The request body is empty.
404 Not Found

Not Found

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

Create a transaction from this listing

POST /p2p/multi_use_listings/{listingId}/create_transaction

Calling /create_transaction with no parameters will create a new transaction with the details provided by the listing.

The optional quantity parameter can be passed to create a transaction for a multiple of the original listing. In this case, the price and charge for the new transaction will also need to be passed.

As an example, consider a listing for a chair with a price of 1234 EUR. If a user wants to buy 10 of these in a single transaction then the charge for the total can be retrieved using GET /p2p/charge?price=1234&currency=usd&quantity=10 (note the addition of the optional quantity parameter at the end). This will return a price of 12340 and an associated charge. These new values must then be passed to /create_transaction with quantity=10, which will create a new transaction with the new pricing information. The new transaction will also include a quantity field, which doesn't have a functional effect on the transaction, but is included for informational purposes.

Note that this functionality is not available for single-use listings, from which only singular transactions may be created.

Offline access is allowed for this endpoint when the user has granted the p2p_tx:offline_create_join scope to the client that is performing the request.

listingId

(no description)

type
integer (int64)
in
path
quantity

(no description)

type
integer (int64)
in
query
price

(no description)

type
integer (int64)
in
query
charge

(no description)

type
integer (int64)
in
query

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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 150,
    "price": 5000
  },
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "listing_id": 1990,
  "listing_type": "multi_use",
  "quantity": 10,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "joined"
}
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. Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_update scope to the client that is performing the request.

listingId

(no description)

type
integer (int64)
in
path

OK

404 Not Found

Not Found

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

Enable this listing

POST /p2p/multi_use_listings/{listingId}/enable

Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_update scope to the client that is performing the request.

listingId

(no description)

type
integer (int64)
in
path

OK

404 Not Found

Not Found

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

Set pricing for this listing

POST /p2p/multi_use_listings/{listingId}/set_deposit_pricing

Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_update scope to the client that is performing the request.

charge_calculator_version: integer (int64)

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

currency: Currency
deposit_charge: integer (int64)

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

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.

listingId

(no description)

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

OK

404 Not Found

Not Found

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

Set the description for this listing

POST /p2p/multi_use_listings/{listingId}/set_description

Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_update scope to the client that is performing the request.

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)
{
  "allows_multi_use": true,
  "created": "2019-12-25T09:00:00.000Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 150,
    "price": 5000
  },
  "description": "Soccer ticket",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "skip_remainder": false
}

Set skip remainder for this listing

POST /p2p/multi_use_listings/{listingId}/set_skip_remainder

Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_update scope to the client that is performing the request.

skip_remainder: boolean
listingId

(no description)

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

OK

404 Not Found

Not Found

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

F2F Single-use Listings

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. Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_create scope to the client that is performing the request.

201 Created

Created

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

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. Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_create scope to the client that is performing the request.

charge_calculator_version: integer (int64)

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

charge_seller: integer (int64)

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

currency: Currency
deposit_charge: integer (int64)

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

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.

description: string

A description of the goods being sold.

role: basic.Role
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
{
  "charge_calculator_version": 5,
  "currency": "eur",
  "deposit_charge": 78,
  "deposit_price": 1234,
  "description": "Soccer ticket",
  "role": "seller"
}
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)
{
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 78,
    "price": 1234
  },
  "description": "Soccer ticket",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "skip_remainder": false
}

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

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)
{
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 150,
    "price": 5000
  },
  "description": "",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "skip_remainder": false
}

Patch listing properties

PATCH /p2p/single_use_listings/{listingId}
charge_calculator_version: integer (int64)

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

currency: Currency
deposit_charge: integer (int64)

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

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.

description: string
skip_remainder: boolean
listingId

(no description)

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

Bad Request

code can be one of the following:

  • empty_body: The request body is empty.
404 Not Found

Not Found

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

Create a transaction from this listing

POST /p2p/single_use_listings/{listingId}/create_transaction

Offline access is allowed for this endpoint when the user has granted the p2p_tx:offline_create_join scope to the client that is performing the request.

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)
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "created": "2019-12-25T09:00:00.000Z",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 150,
    "price": 5000
  },
  "description": "Soccer ticket",
  "id": 1309,
  "joined": "2019-12-25T10:00:00.000Z",
  "listing_id": 1990,
  "listing_type": "single_use",
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "skip_remainder": false,
  "status": "joined"
}
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. Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_update scope to the client that is performing the request.

listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

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

Enable this listing

POST /p2p/single_use_listings/{listingId}/enable

Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_update scope to the client that is performing the request.

listingId

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

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

Set pricing for this listing

POST /p2p/single_use_listings/{listingId}/set_deposit_pricing

Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_update scope to the client that is performing the request.

charge_calculator_version: integer (int64)

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

currency: Currency
deposit_charge: integer (int64)

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

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.

listingId

(no description)

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

Not Found

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

Set the description for this listing

POST /p2p/single_use_listings/{listingId}/set_description

Offline access is allowed for this endpoint when the user has granted the p2p_ls:offline_update scope to the client that is performing the request.

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)
{
  "allows_multi_use": false,
  "created": "2019-12-25T09:00:00.000Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "currency": "eur",
  "deposit_pricing": {
    "charge": 150,
    "price": 5000
  },
  "description": "Soccer ticket",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a",
  "skip_remainder": false
}

Subscriptions

Get the billing period.

GET /recurrent_payments/billing_periods/{billing_period_id}
billing_period_id

(no description)

type
integer (int64)
in
path
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "created": "2019-12-25T09:00:00.000Z",
  "id": 130,
  "paid": "2019-12-26T10:00:00.000Z",
  "status": "tracked",
  "subscription_id": 200,
  "tracked": "2019-12-27T10:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}

Confirm handover for the subscriptions's billing period.

POST /recurrent_payments/billing_periods/{billing_period_id}/confirm_handover
billing_period_id

(no description)

type
integer (int64)
in
path
400 Bad Request

Bad Request

code can be one of the following:

  • billing_period_not_paid
  • handover_already_confirmed
  • funds_already_released
  • handover_confirmation_not_required
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "buyer_handover_confirmed": "2019-12-27T10:00:00.000Z",
  "created": "2019-12-25T09:00:00.000Z",
  "id": 130,
  "paid": "2019-12-26T10:00:00.000Z",
  "status": "handover_confirmed",
  "subscription_id": 200
}
Response Example (400 Bad Request)
{
  "code": "handover_already_confirmed",
  "error": "handover already confirmed"
}

Input tracking details for the subscriptions's billing period.

POST /recurrent_payments/billing_periods/{billing_period_id}/track
carrier: string
tracking_code: string
billing_period_id

(no description)

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

Bad Request

code can be one of the following:

  • billing_period_not_paid
  • tracking_already_added
  • tracking_details_deadline_expired
404 Not Found

Not Found

Response Content-Types: application/json
Response Example (200 OK)
{
  "created": "2019-12-25T09:00:00.000Z",
  "id": 130,
  "paid": "2019-12-26T10:00:00.000Z",
  "status": "tracked",
  "subscription_id": 200,
  "tracked": "2019-12-27T10:00:00.000Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}
Response Example (400 Bad Request)
{
  "code": "tracking_already_added",
  "error": "tracking details already added"
}

Get the Trustap fee for a product

GET /recurrent_payments/charge

This returns the Trustap fee, in the currency's smallest unit, for a product 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 the currency's smallest unit. For example, if a tradingcard is being sold for $12.34 (with currency as usd), then the request for the charge for this product would be /recurrent_payments/charge?price=1234&currency=usd.

type
integer (int64)
in
query
payment_method

The payment method that will be used to pay for the product. This is necessary because different payment methods may result in different fees.

The default value is card.

type
string
in
query
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)
{
  "charge_buyer": 78,
  "charge_seller": 0,
  "currency": "eur"
}
Response Example (400 Bad Request)
{
  "code": "negative_price",
  "error": "`price` cannot be negative"
}

Get subscriptions for the logged-in user

POST /recurrent_payments/me/subscriptions
client_ids: string[]
date_created_from: string
date_created_to: string
exclude_status: string
product_id: integer (int64)
sort_by_order: string
statuses: string[]
subscription_id: integer (int64)
page

(no description)

type
integer (int64)
in
query
page_size

(no description)

type
integer (int64)
in
query
Request Content-Types: application/json
Request Example
{
  "client_ids": [
    "string"
  ],
  "date_created_from": "string",
  "date_created_to": "string",
  "exclude_status": "string",
  "product_id": "integer (int64)",
  "sort_by_order": "string",
  "statuses": [
    "string"
  ],
  "subscription_id": "integer (int64)"
}
400 Bad Request

Bad Request

code can be one of the following:

  • invalid_page
  • page_value_too_low
  • invalid_page_size
  • page_size_too_big
  • negative_page_size
Response Content-Types: application/json
Response Example (200 OK)
{
  "data": [
    {
      "buyer_id": "885bb99f-85bf-47e1-be0d-15e7541c6123",
      "created": "2019-12-25T09:00:00.000Z",
      "id": 1309,
      "product_id": 1564,
      "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
      "status": "created"
    }
  ],
  "page": "integer (int64)",
  "page_size": "integer (int64)",
  "total_count": "integer (int64)",
  "total_pages": "integer (int64)"
}

Get subscription's billing periods for the logged-in user

POST /recurrent_payments/me/subscriptions/{subscription_id}/billing_periods
exclude_status: string
sort_by_order: string
statuses: string[]
subscription_id

(no description)

type
integer (int64)
in
path
page

(no description)

type
integer (int64)
in
query
page_size

(no description)

type
integer (int64)
in
query
Request Content-Types: application/json
Request Example
{
  "exclude_status": "string",
  "sort_by_order": "string",
  "statuses": [
    "string"
  ]
}
400 Bad Request

Bad Request

code can be one of the following:

  • invalid_page
  • page_value_too_low
  • invalid_page_size
  • page_size_too_big
  • negative_page_size
Response Content-Types: application/json
Response Example (200 OK)
{
  "data": [
    {
      "buyer_id": "885bb99f-85bf-47e1-be0d-15e7541c6123",
      "created": "2019-12-25T09:00:00.000Z",
      "id": 1309,
      "product_id": 1564,
      "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
      "status": "created"
    }
  ],
  "page": "integer (int64)",
  "page_size": "integer (int64)",
  "total_count": "integer (int64)",
  "total_pages": "integer (int64)"
}

Create a new product

POST /recurrent_payments/products

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

billing_interval: subscriptions.BillingInterval
charge_buyer: integer (int64)

The charge_buyer value returned from a request to /recurrent_payments/charge.

charge_seller: integer (int64)

The charge_seller value returned from a request to /recurrent_payments/charge.

client_id: string
currency: string

The currency that the price is specified in.

description: string

A description of the goods being sold.

escrow_enabled: boolean
features: string[]

The list of feature flags for this product. Accepted feature flags are -require_handover_confirmation -require_tracking

is_digital: boolean

Whether the goods are phisical or digital.

name: string

The name of the goods being sold.

price: integer (int64)

The price of the goods, 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.

seller_id: string

The Id of the seller of the goods.

Request Content-Types: application/json
Request Example
{
  "billing_interval": "month",
  "charge_buyer": "integer (int64)",
  "charge_seller": "integer (int64)",
  "client_id": "string",
  "currency": "string",
  "description": "string",
  "escrow_enabled": "boolean",
  "features": [
    "string"
  ],
  "is_digital": "boolean",
  "name": "string",
  "price": "integer (int64)",
  "seller_id": "string"
}
201 Created

Created

400 Bad Request

Bad Request

code can be one of the following:

  • incorrect_charge_buyer
  • incorrect_charge_seller
  • negative_price
  • price_too_low
Response Content-Types: