F2F Transactions

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 support@trustap.com
Languages
Servers
https://dev.stage.trustap.com/api/v1/

Online Transactions

Online transactions are used when the goods are delivered using registered mail.

Operations

Clients

Clients represent partner applications.

Operations

Users

Users represent users of the platform.

Operations

Personal

Personal endpoints are used for managing personal details for users, for "Know Your Customer" requirements.

Operations

Notifications

Notifications log updates for users.

Operations

F2F Transactions

F2F2 transactions are used when the goods are delivered in person.

Operations

Get multiple transactions by their IDs

Request

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
Query
idsstringrequired

A comma-separated list of transaction IDs

curl -i -X GET \
  'https://dev.stage.trustap.com/api/v1/p2p/batch/transactions?ids=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/jsonArray [
buyer_handover_confirmedstring(date-time)
Example: "2019-12-25T16:00:00Z"
buyer_idstring
Example: "feb33a87-3917-4538-9260-127c8a6b5232"
buyer_is_guestboolean
cancellationobject(p2p.Cancellation)
cancelledstring(date-time)
claimed_by_buyerstring(date-time)
claimed_by_sellerstring(date-time)
client_idstringrequired
Example: "trustap-app"
complainedstring(date-time)
complaintobject(p2p.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"
deposit_acceptedstring(date-time)
Example: "2019-12-25T12:00:00Z"
deposit_paidstring(date-time)
Example: "2019-12-25T11:00:00Z"
deposit_pricingobject(p2p.Pricing)required
Example: {"charge":78,"price":1234}
deposit_pricing.​chargeinteger(int64)required
Example: 78
deposit_pricing.​charge_international_paymentinteger(int64)
deposit_pricing.​charge_sellerinteger(int64)required
deposit_pricing.​deposit_fee_multiplierobject(p2p.DepositFeeMultiplier)
deposit_pricing.​priceinteger(int64)required
Example: 1234
deposit_refundedstring(date-time)
deposit_reviewobject(p2p.Review)
deposit_review_flaggedstring(date-time)
descriptionstringrequired
Example: "Soccer ticket"
funds_releasedstring(date-time)
Example: "2019-12-25T17:00:00Z"
idinteger(int64)required
Example: 1309
is_deposit_payment_in_progressbooleanrequired

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

is_remainder_payment_in_progressbooleanrequired

If the remainder 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_idstring

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

listing_typestring(p2p.ListingType)
Enum"single_use""multi_use""prepaid"
Example: "single_use"
pricedstring(date-time)
Example: "2019-12-25T13:00:00Z"
pricingobject(p2p.Pricing)
Example: {"charge":78,"price":1234}
quantityinteger(int64)required
refundedstring(date-time)
rejectedstring(date-time)
relased_to_sellerstring(date-time)
released_to_sellerboolean
remainder_paidstring(date-time)
Example: "2019-12-25T14:00:00Z"
remainder_reviewobject(p2p.Review)
remainder_review_flaggedstring(date-time)
remainder_skippedstring(date-time)
seller_handover_confirmedstring(date-time)
Example: "2019-12-25T15:00:00Z"
seller_idstring
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
seller_is_guestboolean
skip_remainderbooleanrequired

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

statusstringrequired
Example: "funds_released"
]
Response
application/json
[
  {
    "buyer_handover_confirmed": "2019-12-25T16:00:00Z",
    "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
    "client_id": "trustap-app",
    "created": "2019-12-25T09:00:00Z",
    "currency": "eur",
    "deposit_accepted": "2019-12-25T12:00:00Z",
    "deposit_paid": "2019-12-25T11:00:00Z",
    "deposit_pricing": { … },
    "description": "Soccer ticket",
    "funds_released": "2019-12-25T17:00:00Z",
    "id": 1309,
    "is_deposit_payment_in_progress": false,
    "is_remainder_payment_in_progress": false,
    "joined": "2019-12-25T10:00:00Z",
    "priced": "2019-12-25T13:00:00Z",
    "pricing": { … },
    "remainder_paid": "2019-12-25T14:00:00Z",
    "seller_handover_confirmed": "2019-12-25T15:00:00Z",
    "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7",
    "skip_remainder": false,
    "status": "funds_released"
  }
]

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

Request

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.

Query
currencystringrequired

The currency that the price is specified in.

priceinteger(int64)required

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.

fee_multipliernumber(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.

quantityinteger(int64)

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.

payment_methodstring

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.

curl -i -X GET \
  'https://dev.stage.trustap.com/api/v1/p2p/charge?currency=string&fee_multiplier=0.1&payment_method=string&price=0&quantity=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
chargeinteger(int64)required

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

Example: 78
charge_calculator_versioninteger(int64)required

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

This property is present for error-handling purposes. The Trustap API allows apps and users to query how much Trustap will charge for a transaction before creating a transaction. Trustap then requires the queried charge to be provided when creating a transaction or listing. At this point the charge is calculated again and checked against the provided charge, to ensure that the charge calculated for the new resource is the same as the one shown to the user. In the unlikely event that the Trustap charge calculator used to calculate the charge has been updated, then the charge_calculator_version property will be used to return an incorrect_calc_version to the API client, which will indicate that the /charge endpoint should be queried again to get the newest charge value.

Example: 5
charge_sellerinteger(int64)required

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

currencystringrequired
Example: "eur"
priceinteger(int64)required
Response
application/json
{
  "charge": 78,
  "charge_calculator_version": 5,
  "currency": "eur"
}

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

Request

Transactions are currently sorted by ID.

Query
before_idinteger(int64)>= 0

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

after_idinteger(int64)>= 0

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

limitinteger(int64)[ 1 .. 50 ]

The maximum number of transactions to return

Default 25
curl -i -X GET \
  'https://dev.stage.trustap.com/api/v1/p2p/me/transactions?after_id=0&before_id=0&limit=25' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/jsonArray [
buyer_handover_confirmedstring(date-time)
Example: "2019-12-25T16:00:00Z"
buyer_idstring
Example: "feb33a87-3917-4538-9260-127c8a6b5232"
buyer_is_guestboolean
cancellationobject(p2p.Cancellation)
cancelledstring(date-time)
claimed_by_buyerstring(date-time)
claimed_by_sellerstring(date-time)
client_idstringrequired
Example: "trustap-app"
complainedstring(date-time)
complaintobject(p2p.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"
deposit_acceptedstring(date-time)
Example: "2019-12-25T12:00:00Z"
deposit_paidstring(date-time)
Example: "2019-12-25T11:00:00Z"
deposit_pricingobject(p2p.Pricing)required
Example: {"charge":78,"price":1234}
deposit_pricing.​chargeinteger(int64)required
Example: 78
deposit_pricing.​charge_international_paymentinteger(int64)
deposit_pricing.​charge_sellerinteger(int64)required
deposit_pricing.​deposit_fee_multiplierobject(p2p.DepositFeeMultiplier)
deposit_pricing.​priceinteger(int64)required
Example: 1234
deposit_refundedstring(date-time)
deposit_reviewobject(p2p.Review)
deposit_review_flaggedstring(date-time)
descriptionstringrequired
Example: "Soccer ticket"
funds_releasedstring(date-time)
Example: "2019-12-25T17:00:00Z"
idinteger(int64)required
Example: 1309
is_deposit_payment_in_progressbooleanrequired

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

is_remainder_payment_in_progressbooleanrequired

If the remainder 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_idstring

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

listing_typestring(p2p.ListingType)
Enum"single_use""multi_use""prepaid"
Example: "single_use"
pricedstring(date-time)
Example: "2019-12-25T13:00:00Z"
pricingobject(p2p.Pricing)
Example: {"charge":78,"price":1234}
quantityinteger(int64)required
refundedstring(date-time)
rejectedstring(date-time)
relased_to_sellerstring(date-time)
released_to_sellerboolean
remainder_paidstring(date-time)
Example: "2019-12-25T14:00:00Z"
remainder_reviewobject(p2p.Review)
remainder_review_flaggedstring(date-time)
remainder_skippedstring(date-time)
seller_handover_confirmedstring(date-time)
Example: "2019-12-25T15:00:00Z"
seller_idstring
Example: "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
seller_is_guestboolean
skip_remainderbooleanrequired

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

statusstringrequired
Example: "funds_released"
]
Response
application/json
[
  {
    "buyer_handover_confirmed": "2019-12-25T16:00:00Z",
    "buyer_id": "feb33a87-3917-4538-9260-127c8a6b5232",
    "created": "2019-12-25T09:00:00Z",
    "currency": "eur",
    "deposit_accepted": "2019-12-25T12:00:00Z",
    "deposit_paid": "2019-12-25T11:00:00Z",
    "deposit_pricing": { … },
    "description": "Soccer ticket",
    "funds_released": "2019-12-25T17:00:00Z",
    "id": 1309,
    "joined": "2019-12-25T10:00:00Z",
    "priced": "2019-12-25T13:00:00Z",
    "pricing": { … },
    "remainder_paid": "2019-12-25T14:00:00Z",
    "seller_handover_confirmed": "2019-12-25T15:00:00Z",
    "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:00Z",
    "currency": "eur",
    "deposit_pricing": { … },
    "description": "Soccer ticket",
    "id": 609,
    "join_code": "c9cd6a9d-1096-4d38-b4aa-2c354beac845",
    "skip_remainder": false,
    "status": "created"
  }
]

Online Multi-use Listings

These endpoints are no longer supported. We do not recommend using these endpoints.

Operations

Online Single-use Listings

These endpoints are no longer supported. We do not recommend using these endpoints.

Operations

F2F Multi-use Listings

These endpoints are no longer supported. We do not recommend using these endpoints.

Operations

F2F Single-use Listings

These endpoints are no longer supported. We do not recommend using these endpoints.

Operations