# Upgrade from Trustap API v1 to API v2 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. ## What has changed ### Base URIs | 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/` | ### Flow models 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 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 API v2 transaction IDs are prefixed with `tx_`. ```JSON API v2 sample transaction ID tx_01kq7pz74mffj9x5vsesqkve08 ``` API v1 ```JSON API v1 sample transaction ID 346545 ``` ### Transaction objects The 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 `pricing` object. * Lifecycle timestamps are now available in an `events` object. * Deadlines are grouped under `deadlines`. * Transaction IDs are now prefixed strings. API v2 ```JSON API v2 sample transaction object { "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 v1 ```JSON API v1 sample transaction object { "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "charge": 720, "charge_seller": 0, "client_id": "118931fb-e3fc-44fc-8a86-06a79d26972c", "created": "2025-03-19T09:55:36Z", "currency": "gbp", "description": "Online no deposit", "id": 25439, "is_payment_in_progress": false, "joined": "2025-03-19T09:55:36Z", "price": 20000, "quantity": 1, "seller_id": "1-886e3c26-b585-4c92-a93b-e3c84b9b32e9", "status": "joined" } ``` ### Webhooks API v2 introduces new webhook event codes and a redesigned payload format. Changes include: * Event codes now use the `tx.*` naming convention. * `target_id` now contains the new transaction ID format. * `target_preview` matches the new transaction object. Review the API v2 [webhooks guide](/docs/concepts/webhooks) for more details. API v2 ```JSON API v2 sample webhook payload { "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": {} } ``` API v1 ```JSON API v1 sample webhook payload { "code": "basic_tx.paid", "user_id": "1-b7f83d35-37af-43df-acdd-851976179535", "target_id": "32698", "target_preview": { "id": 32698, "status": "paid", "currency": "eur", "quantity": 1, "price": 30000, "charge": 130, "charge_seller": 0, "charge_buyer_client": 0, "charge_seller_client": 0, "description": "Blue t-shirt with owl decal", "created": "2026-02-11T12:40:54Z", "is_payment_in_progress": false, "client_id": "84a89340-6827-4f90-8cbd-f412ae72b5a7", "buyer_id": "1-b7f83d35-37af-43df-acdd-851976179535", "seller_id": "1-fdc6744b-e16d-48af-8b82-e4ffb4ae6168", "joined": "2026-02-11T12:40:54Z", "paid": "2026-02-11T12:42:13Z", "tracking_details_window_started": "2026-02-11T12:42:13Z", "tracking_details_deadline": "2026-02-11T12:42:13Z" }, "time": "2026-02-11T12:42:13.161481114Z", "metadata": {} } ``` ### Endpoints Endpoint paths have changed throughout API v2. Refer to the [API reference](/apis/openapi) when updating your integration.