Online Transactions
/
Get the list of Shippo shipping rates available

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

Create a new transaction with both users

Request

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.

Bodyapplication/jsonrequired
buyer_idstringrequired

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

chargeinteger(int64)required

The charge value returned from a request to /charge.

charge_calculator_versioninteger(int64)required

The charge_calculator_version value returned from a request to /charge.

charge_sellerinteger(int64)

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

client_idstring
creator_rolestring(basic.Role)required
Enum"buyer""seller"
Example: "buyer"
currencystring(Currency)required
Enum"aud""eur""gbp""myr""pln""sek""usd""huf"
Example: "eur"
descriptionstringrequired

A description of the goods being sold.

featuresArray of strings(basic.Feature)

features contains flags that modify the transaction flow.

Items Enum"require_seller_acceptance""use_hr_post""use_shippo"
Example: ["require_seller_acceptance"]
postage_feeinteger(int64)

The custom postage fee, this fee only applies in the case postage fee feature flag is enabled.

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.

seller_idstringrequired

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

curl -i -X POST \
  https://dev.stage.trustap.com/api/v1/me/transactions/create_with_guest_user \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "buyer_id": "1-bd5bb99j-95bf-87e2-ce0d-95e7541c6ad5",
      "charge": 78,
      "charge_calculator_version": 5,
      "charge_seller": 0,
      "creator_role": "seller",
      "currency": "eur",
      "description": "Soccer ticket",
      "price": 1234,
      "seller_id": "ad5bb99f-85bf-47e1-be0d-15e7541c6ad7"
    }
  ]'

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": "***"
  }
}

Get the list of Shippo shipping rates available

Request

This returns the list of Shippo shipping rates available for the addreses provided i.e sender's address and recipient's address.

Bodyapplication/jsonrequired
currencystringrequired
Example: "EUR"
customs_certifyboolean
Example: true
customs_certify_signerstring
Example: "Joe Doe"
customs_descriptionstring
Example: "T-Shirt"
customs_eel_pfcstring
customs_incotermstring
Example: "DDU"
customs_mass_unitstring
Example: "lb"
customs_net_weightnumber(double)
Example: 5
customs_non_delivery_optionstring
Enum"return""abandon"
Example: "return"
customs_origin_countrystring
Example: "US"
customs_quantityinteger(int64)
Example: 20
customs_value_amountstring
Example: 200
customs_value_currencystring
Example: "USD"
parcel_distance_unitstring(basic.DistanceUnit)required
Enum"in""cm"
Example: "cm"
parcel_heightnumber(double)required
Example: 10
parcel_lengthnumber(double)required
parcel_mass_unitstring(basic.MassUnit)required
Enum"lb""kg"
Example: "kg"
parcel_weightnumber(double)required
Example: 10
parcel_widthnumber(double)required
Example: 10
recipient_citystringrequired
Example: "New York"
recipient_countrystringrequired
Example: "us"
recipient_full_namestringrequired
Example: "Ivan Horvat"
recipient_phonestringrequired
Example: 123456789
recipient_statestringrequired
Example: "New York"
recipient_street_1stringrequired
Example: "21-27 Marshall Court"
recipient_street_2string
recipient_zip_codestringrequired
sender_citystringrequired
Example: "Altona"
sender_countrystringrequired
Example: "au"
sender_full_namestringrequired
Example: "Ana Potter"
sender_phonestringrequired
Example: 123456789
sender_statestringrequired
Example: "Victoria"
sender_street_1stringrequired
Example: "21-27 Marshall Court"
sender_street_2string
sender_zip_codestringrequired
curl -i -X POST \
  https://dev.stage.trustap.com/api/v1/shippo_shipping_rates \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "EUR",
    "customs_certify": true,
    "customs_certify_signer": "Joe Doe",
    "customs_description": "T-Shirt",
    "customs_incoterm": "DDU",
    "customs_mass_unit": "lb",
    "customs_net_weight": 5,
    "customs_non_delivery_option": "return",
    "customs_origin_country": "US",
    "customs_quantity": 20,
    "customs_value_amount": 200,
    "customs_value_currency": "USD",
    "parcel_distance_unit": "cm",
    "parcel_height": 10,
    "parcel_lenght": 10,
    "parcel_mass_unit": "lb",
    "parcel_weight": 10,
    "parcel_width": 10,
    "recipient_city": "New York",
    "recipient_country": "us",
    "recipient_full_name": "Ivan Horvat",
    "recipient_phone": 123456789,
    "recipient_postal_code": 10000,
    "recipient_state": "New York",
    "recipient_street_1": "21-27 Marshall Court",
    "sender_city": "Altona",
    "sender_country": "au",
    "sender_full_name": "Ana Potter",
    "sender_phone": 123456789,
    "sender_postal_code": 10000,
    "sender_state": "Victoria",
    "sender_street_1": "21-27 Marshall Court"
  }'

Responses

OK

Bodyapplication/json
ratesArray of objects(basic.ShippoRate)required
rates[].​amountstringrequired
rates[].​amount_localstringrequired
rates[].​arrives_bystring
rates[].​attributesArray of stringsrequired
rates[].​currencystringrequired
rates[].​currency_localstringrequired
rates[].​duration_termsstringrequired
rates[].​estimated_daysinteger(int64)required
rates[].​idstringrequired
rates[].​providerstringrequired
rates[].​provider_imagestringrequired
shipment_idstringrequired
Response
application/json
{
  "rates": [
    { … }
  ],
  "shipment_id": "string"
}

Get the supported carriers

Request

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.

curl -i -X GET \
  https://dev.stage.trustap.com/api/v1/supported_carriers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/jsonArray [
codestringrequired
namestringrequired
]
Response
application/json
[
  {
    "code": "an-post",
    "name": "An Post"
  },
  {
    "code": "fedex",
    "name": "FedEx"
  },
  {
    "code": "ups",
    "name": "UPS"
  },
  {
    "code": "usps",
    "name": "USPS"
  }
]

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

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