Online Multi-use Listings

Trustap API (0.1.0)

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.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
E-mail help@trustap.com
Languages
Servers
https://dev.stage.trustap.com/api/v1/

Online Transactions

Operations

Clients

Operations

Users

Operations

Personal

Operations

Online Multi-use Listings

Operations

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

Request

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.

Bodyapplication/jsonrequired
chargeinteger(int64)required

The charge value returned from a request to /charge.

Example: 78
charge_calculator_versioninteger(int64)required

The charge_calculator_version value returned from a request to /charge.

Example: 5
charge_sellerinteger(int64)

The charge_seller value returned from a request to /charge.

currencystring(Currency)required
Enum"aud""eur""gbp""myr""pln""sek""usd""huf"
Example: "eur"
descriptionstringrequired

A description of the goods being sold.

Example: "Soccer ticket"
priceinteger(int64)required

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.

Example: 1234
rolestring(basic.Role)required
Enum"buyer""seller"
Example: "buyer"
curl -i -X POST \
  https://dev.stage.trustap.com/api/v1/me/multi_use_listings/create \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "charge": 78,
    "charge_calculator_version": 5,
    "currency": "eur",
    "description": "Soccer ticket",
    "price": 1234,
    "role": "seller"
  }'

Responses

Created

Bodyapplication/json
createdstring(date-time)required
Example: "2019-12-25T09:00:00Z"
creator_idstringrequired
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
creator_rolestring(basic.Role)required
Enum"buyer""seller"
Example: "buyer"
currencystring
descriptionstring
disabledstring(date-time)
idstringrequired
Example: "77f36253-7a43-4d47-897d-f73dd208e17a"
pricingobject(basic.Pricing)
Example: {"charge":78,"price":1234}
Response
application/json
{
  "created": "2019-12-25T09:00:00Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a"
}

Delete this listing

Request

Path
listing_idstringrequired
curl -i -X DELETE \
  'https://dev.stage.trustap.com/api/v1/multi_use_listings/{listing_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

No Content

Get a listing by its ID

Request

Path
listing_idstringrequired
curl -i -X GET \
  'https://dev.stage.trustap.com/api/v1/multi_use_listings/{listing_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
createdstring(date-time)required
Example: "2019-12-25T09:00:00Z"
creator_idstringrequired
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
creator_rolestring(basic.Role)required
Enum"buyer""seller"
Example: "buyer"
currencystring
descriptionstring
disabledstring(date-time)
idstringrequired
Example: "77f36253-7a43-4d47-897d-f73dd208e17a"
pricingobject(basic.Pricing)
Example: {"charge":78,"price":1234}
Response
application/json
{
  "created": "2019-12-25T09:00:00Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a"
}

Patch listing properties

Request

Path
listing_idstringrequired
Bodyapplication/jsonrequired
chargeinteger(int64)

The charge value returned from a request to /charge.

Example: 78
charge_calculator_versioninteger(int64)

The charge_calculator_version value returned from a request to /charge.

Example: 5
charge_sellerinteger(int64)

The charge_seller value returned from a request to /charge.

currencystring(Currency)
Enum"aud""eur""gbp""myr""pln""sek""usd""huf"
Example: "eur"
descriptionstring
Example: "Soccer ticket"
priceinteger(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.

Example: 1234
curl -i -X PATCH \
  'https://dev.stage.trustap.com/api/v1/multi_use_listings/{listing_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "charge": 78,
    "charge_calculator_version": 5,
    "currency": "eur",
    "description": "Soccer ticket",
    "price": 1234
  }'

Responses

OK

Bodyapplication/json
createdstring(date-time)required
Example: "2019-12-25T09:00:00Z"
creator_idstringrequired
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
creator_rolestring(basic.Role)required
Enum"buyer""seller"
Example: "buyer"
currencystring
descriptionstring
disabledstring(date-time)
idstringrequired
Example: "77f36253-7a43-4d47-897d-f73dd208e17a"
pricingobject(basic.Pricing)
Example: {"charge":78,"price":1234}
Response
application/json
{
  "created": "2019-12-25T09:00:00Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a"
}

Create a transaction from this listing

Request

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.

Path
listing_idstringrequired
Query
quantityinteger(int64)
priceinteger(int64)
chargeinteger(int64)
payment_methodstring
curl -i -X POST \
  'https://dev.stage.trustap.com/api/v1/multi_use_listings/{listing_id}/create_transaction?charge=0&payment_method=string&price=0&quantity=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Created

Bodyapplication/json
amount_refundedinteger(int64)
amount_releasedinteger(int64)
buyer_idstring
Example: "feb33a87-3917-4538-9260-127c8a6b5232"
cancelledstring(date-time)
chargeinteger(int64)required
Example: 78
charge_international_paymentinteger(int64)
charge_postage_buyerinteger(int64)
charge_postage_clientinteger(int64)
charge_sellerinteger(int64)required
claimed_by_buyerstring(date-time)
client_idstringrequired
Example: "trustap-app"
complainedstring(date-time)
complaintobject(Complaint)
Example: {"description":"Item was fake"}
complaint_period_deadlinestring(date-time)
complaint_period_endedstring(date-time)
createdstring(date-time)required
Example: "2019-12-25T09:00:00Z"
currencystringrequired

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

Example: "eur"
deliveredstring(date-time)
Example: "2019-12-25T13:00:00Z"
deniedstring(date-time)
descriptionstringrequired
Example: "Soccer ticket"
funds_releasedstring(date-time)
Example: "2019-12-26T14:00:00Z"
idinteger(int64)required
Example: 1309
is_payment_in_progressbooleanrequired

If the transaction is paid via a delayed payment method, such as SEPA debit, this field will be true until the payment has fully succeeded or failed.

join_codestring
joinedstring(date-time)
Example: "2019-12-25T10:00:00Z"
listing_creator_acceptedstring(date-time)
listing_creator_rejectedstring(date-time)
listing_idstring

If the transaction is created from a listing then this is the ID of that listing; otherwise this property is omitted.

listing_typestring(ListingType)
Enum"single_use""multi_use"
Example: "single_use"
paidstring(date-time)
Example: "2019-12-25T11:00:00Z"
payment_acceptedstring(date-time)
payment_refundedstring(date-time)
posta_hr_trackingobject(PostaHrTracking)
Example: {"barcode":"ABC123456","barcode_generated":"2019-12-26T14:00:00Z"}
priceinteger(int64)required
Example: 1234
quantityinteger(int64)required
Example: 1
released_to_sellerboolean
reviewobject(basic.Review)
review_flaggedstring(date-time)
seller_idstring
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
shippo_transaction_idstring
statusstringrequired
Example: "funds_released"
trackedstring(date-time)
Example: "2019-12-25T12:00:00Z"
trackingobject(Tracking)
Example: {"carrier":"ups","tracking_code":"***"}
tracking_details_deadlinestring(date-time)
tracking_details_window_startedstring(date-time)
Response
application/json
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "charge_seller": 0,
  "client_id": "trustap-app",
  "created": "2019-12-25T09:00:00Z",
  "currency": "eur",
  "delivered": "2019-12-25T13:00:00Z",
  "description": "Soccer ticket",
  "funds_released": "2019-12-26T14:00:00Z",
  "id": 1309,
  "is_payment_in_progress": false,
  "joined": "2019-12-25T10:00:00Z",
  "paid": "2019-12-25T11:00:00Z",
  "posta_hr_tracking": {
    "barcode": "ABC12345",
    "barcode_generated": "2019-12-25T12:00:00Z"
  },
  "price": 1234,
  "quantity": 1,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "funds_released",
  "tracked": "2019-12-25T12:00:00Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}

Create a transaction from this listing

Request

Path
listing_idstringrequired
curl -i -X POST \
  'https://dev.stage.trustap.com/api/v1/multi_use_listings/{listing_id}/create_transaction_with_guest_buyer' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Created

Bodyapplication/json
amount_refundedinteger(int64)
amount_releasedinteger(int64)
buyer_idstring
Example: "feb33a87-3917-4538-9260-127c8a6b5232"
cancelledstring(date-time)
chargeinteger(int64)required
Example: 78
charge_international_paymentinteger(int64)
charge_postage_buyerinteger(int64)
charge_postage_clientinteger(int64)
charge_sellerinteger(int64)required
claimed_by_buyerstring(date-time)
client_idstringrequired
Example: "trustap-app"
complainedstring(date-time)
complaintobject(Complaint)
Example: {"description":"Item was fake"}
complaint_period_deadlinestring(date-time)
complaint_period_endedstring(date-time)
createdstring(date-time)required
Example: "2019-12-25T09:00:00Z"
currencystringrequired

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

Example: "eur"
deliveredstring(date-time)
Example: "2019-12-25T13:00:00Z"
deniedstring(date-time)
descriptionstringrequired
Example: "Soccer ticket"
funds_releasedstring(date-time)
Example: "2019-12-26T14:00:00Z"
idinteger(int64)required
Example: 1309
is_payment_in_progressbooleanrequired

If the transaction is paid via a delayed payment method, such as SEPA debit, this field will be true until the payment has fully succeeded or failed.

join_codestring
joinedstring(date-time)
Example: "2019-12-25T10:00:00Z"
listing_creator_acceptedstring(date-time)
listing_creator_rejectedstring(date-time)
listing_idstring

If the transaction is created from a listing then this is the ID of that listing; otherwise this property is omitted.

listing_typestring(ListingType)
Enum"single_use""multi_use"
Example: "single_use"
paidstring(date-time)
Example: "2019-12-25T11:00:00Z"
payment_acceptedstring(date-time)
payment_refundedstring(date-time)
posta_hr_trackingobject(PostaHrTracking)
Example: {"barcode":"ABC123456","barcode_generated":"2019-12-26T14:00:00Z"}
priceinteger(int64)required
Example: 1234
quantityinteger(int64)required
Example: 1
released_to_sellerboolean
reviewobject(basic.Review)
review_flaggedstring(date-time)
seller_idstring
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
shippo_transaction_idstring
statusstringrequired
Example: "funds_released"
trackedstring(date-time)
Example: "2019-12-25T12:00:00Z"
trackingobject(Tracking)
Example: {"carrier":"ups","tracking_code":"***"}
tracking_details_deadlinestring(date-time)
tracking_details_window_startedstring(date-time)
Response
application/json
{
  "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
  "charge": 78,
  "charge_seller": 0,
  "client_id": "trustap-app",
  "created": "2019-12-25T09:00:00Z",
  "currency": "eur",
  "delivered": "2019-12-25T13:00:00Z",
  "description": "Soccer ticket",
  "funds_released": "2019-12-26T14:00:00Z",
  "id": 1309,
  "is_payment_in_progress": false,
  "joined": "2019-12-25T10:00:00Z",
  "paid": "2019-12-25T11:00:00Z",
  "posta_hr_tracking": {
    "barcode": "ABC12345",
    "barcode_generated": "2019-12-25T12:00:00Z"
  },
  "price": 1234,
  "quantity": 1,
  "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "status": "funds_released",
  "tracked": "2019-12-25T12:00:00Z",
  "tracking": {
    "carrier": "ups",
    "tracking_code": "***"
  }
}

Disable this listing

Request

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

Path
listing_idstringrequired
curl -i -X POST \
  'https://dev.stage.trustap.com/api/v1/multi_use_listings/{listing_id}/disable' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
createdstring(date-time)required
Example: "2019-12-25T09:00:00Z"
creator_idstringrequired
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
creator_rolestring(basic.Role)required
Enum"buyer""seller"
Example: "buyer"
currencystring
descriptionstring
disabledstring(date-time)
idstringrequired
Example: "77f36253-7a43-4d47-897d-f73dd208e17a"
pricingobject(basic.Pricing)
Example: {"charge":78,"price":1234}
Response
application/json
{
  "created": "2019-12-25T09:00:00Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a"
}

Enable this listing

Request

Path
listing_idstringrequired
curl -i -X POST \
  'https://dev.stage.trustap.com/api/v1/multi_use_listings/{listing_id}/enable' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
createdstring(date-time)required
Example: "2019-12-25T09:00:00Z"
creator_idstringrequired
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
creator_rolestring(basic.Role)required
Enum"buyer""seller"
Example: "buyer"
currencystring
descriptionstring
disabledstring(date-time)
idstringrequired
Example: "77f36253-7a43-4d47-897d-f73dd208e17a"
pricingobject(basic.Pricing)
Example: {"charge":78,"price":1234}
Response
application/json
{
  "created": "2019-12-25T09:00:00Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a"
}

Set description for this listing

Request

Path
listing_idstringrequired
Bodyapplication/jsonrequired
descriptionstringrequired
Example: "Soccer ticket"
curl -i -X POST \
  'https://dev.stage.trustap.com/api/v1/multi_use_listings/{listing_id}/set_description' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Soccer ticket"
  }'

Responses

OK

Bodyapplication/json
createdstring(date-time)required
Example: "2019-12-25T09:00:00Z"
creator_idstringrequired
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
creator_rolestring(basic.Role)required
Enum"buyer""seller"
Example: "buyer"
currencystring
descriptionstring
disabledstring(date-time)
idstringrequired
Example: "77f36253-7a43-4d47-897d-f73dd208e17a"
pricingobject(basic.Pricing)
Example: {"charge":78,"price":1234}
Response
application/json
{
  "created": "2019-12-25T09:00:00Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a"
}

Set pricing for this listing

Request

Path
listing_idstringrequired
Bodyapplication/jsonrequired
chargeinteger(int64)required

The charge value returned from a request to /charge.

Example: 78
charge_calculator_versioninteger(int64)required

The charge_calculator_version value returned from a request to /charge.

Example: 5
charge_sellerinteger(int64)

The charge_seller value returned from a request to /charge.

currencystring(Currency)required
Enum"aud""eur""gbp""myr""pln""sek""usd""huf"
Example: "eur"
priceinteger(int64)required

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.

Example: 1234
curl -i -X POST \
  'https://dev.stage.trustap.com/api/v1/multi_use_listings/{listing_id}/set_pricing' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "charge": 78,
    "charge_calculator_version": 5,
    "currency": "eur",
    "price": 1234
  }'

Responses

OK

Bodyapplication/json
createdstring(date-time)required
Example: "2019-12-25T09:00:00Z"
creator_idstringrequired
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
creator_rolestring(basic.Role)required
Enum"buyer""seller"
Example: "buyer"
currencystring
descriptionstring
disabledstring(date-time)
idstringrequired
Example: "77f36253-7a43-4d47-897d-f73dd208e17a"
pricingobject(basic.Pricing)
Example: {"charge":78,"price":1234}
Response
application/json
{
  "created": "2019-12-25T09:00:00Z",
  "creator_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
  "id": "77f36253-7a43-4d47-897d-f73dd208e17a"
}

Notifications

Operations

Online Single-use Listings

Operations

F2F Transactions

Operations

F2F Multi-use Listings

Operations

F2F Single-use Listings

Operations

Subscriptions

Operations