API v2 introduces a number of changes to transaction models, identifiers, webhook payloads, and endpoint structure. This guide highlights the most important differences you'll encounter when upgrading. It isn't an exhaustive list, so you should also review the API v2 guides and endpoint reference when updating your integration.
Use the following is a high level list to understand some of the fundamental changes to look out for.
| Environment | API v1 | API v2 |
|---|---|---|
| Sandbox | https://dev.stage.trustap.com/api/v1/ | https://api.test.trustap.com/v2/ |
| Production | https://dev.trustap.com/api/v1/ | https://api.trustap.com/v2/ |
In API v1, there were two separate transaction models: an online flow, where a product was delivered by courier, and a face-to-face flow, where the buyer and seller met to physically hand over the product. Each flow had its own transaction model and its own set of endpoints, which made integration confusing at times.
API v2 replaces the separate online and face-to-face transaction models with a single transaction resource. The same endpoints are used regardless of whether an item is shipped or exchanged in person.
Transaction IDs are now globally unique string identifiers instead of integers. If your integration stores transaction IDs or validates them as numeric values, you'll need to update your database schema and application logic.
API v2 transaction IDs are prefixed with tx_.
tx_01kq7pz74mffj9x5vsesqkve08The transaction object has been redesigned. Notable changes include the following.
- Buyer and seller information is now grouped into nested objects.
- Pricing information is contained within a
pricingobject. - Lifecycle timestamps are now available in an
eventsobject. - Deadlines are grouped under
deadlines. - Transaction IDs are now prefixed strings.
{
"buyer": {
"id": "1-def29dfe-8626-48a2-8863-b6fdf2b96ff0",
"is_guest": true
},
"client_id": "5ad5451d-70c7-43c6-86c9-e1d90556856c",
"deadlines": {
"complaints": null
},
"description": "Trustap socks",
"events": {
"by_key": {
"created": "2026-04-27T14:54:51Z",
"joined": "2026-04-27T14:54:51Z"
},
"by_time": [
{
"at": "2026-04-27T14:54:51Z",
"code": "created"
},
{
"at": "2026-04-27T14:54:51Z",
"code": "joined"
}
]
},
"id": "tx_01kq7pz74mffj9x5vsesqkve08",
"payment_link": "https://actions.stage.trustap.com/transactions/tx_01kq7pz74mffj9x5vsesqkve08/pay",
"pricing": {
"amount": 20000,
"amount_extra": 0,
"currency": "gbp",
"fees": {
"buyer": 640,
"buyer_client": 0,
"seller": 0,
"seller_client": 0
}
},
"seller": {
"id": "1-3f546125-2ec2-4b14-87f6-54a14ae73e98",
"is_guest": true
},
"status": "joined"
}API v2 introduces new webhook event codes and a redesigned payload format. Changes include:
- Event codes now use the
tx.*naming convention. target_idnow contains the new transaction ID format.target_previewmatches the new transaction object.
Review the API v2 webhooks guide for more details.
{
"code": "tx.paid",
"user_id": "1-0811c9c1-2a9b-4b06-ba7d-16b693f5c2b2",
"target_id": "tx_01kq9gj63sf4pbpesq9kna5ysa",
"target_preview": {
"buyer": {
"id": "1-0811c9c1-2a9b-4b06-ba7d-16b693f5c2b2",
"is_guest": true
},
"client_id": "e12c9fe5-bd07-47fd-81ec-263b6aaac8d6",
"deadlines": {
"complaints": null
},
"description": "v2 Payment",
"events": {
"by_key": {
"created": "2026-04-28T07:41:21Z",
"joined": "2026-04-28T07:41:21Z",
"paid": "2026-04-28T07:41:25Z"
},
"by_time": [
{
"at": "2026-04-28T07:41:21Z",
"code": "created"
},
{
"at": "2026-04-28T07:41:21Z",
"code": "joined"
},
{
"at": "2026-04-28T07:41:25Z",
"by": "1-0811c9c1-2a9b-4b06-ba7d-16b693f5c2b2",
"code": "paid"
}
]
},
"id": "tx_01kq9gj63sf4pbpesq9kna5ysa",
"pricing": {
"amount": 1000,
"amount_extra": 0,
"currency": "eur",
"fees": {
"buyer": 50,
"buyer_client": 0,
"seller": 0,
"seller_client": 0
}
},
"seller": {
"id": "1-e2f0d161-41c7-429d-8cee-7e524e61756f",
"is_guest": true
},
"status": "paid"
},
"time": "2026-04-28T07:41:25.213691597Z",
"metadata": {}
}Endpoint paths have changed throughout API v2. Refer to the API reference when updating your integration.