{"templateId":"markdown","versions":[{"version":"v1.0","label":"v1.0","link":"/docs/v1.0/intro/upgrade","default":false,"active":false,"folderId":"a2557b8d"},{"version":"v2.0","label":"v2.0 (latest version)","link":"/docs/intro/upgrade","default":true,"active":true,"folderId":"a2557b8d"}],"sharedDataIds":{"sidebar":"sidebar-docs/@v1.0/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab"]},"type":"markdown"},"seo":{"title":"Upgrade from Trustap API v1 to API v2","description":"Learn about difference between the Trustap API v1 and Trustap API v2.","llmstxt":{"hide":false,"title":"Trustap API","description":"Trustap is an API for end-to-end transaction solution that seamlessly integrates payments, fulfillment, and support into your marketplace. Trustap is an escrow API service facilitating secure transactions.","sections":[{"title":"Intro","description":"Trustap API introduction.","includeFiles":["docs/v2.0/intro/*.md"],"excludeFiles":[]},{"title":"Concepts","description":"Trustap Concepts","includeFiles":["docs/v2.0/concepts/*.md"],"excludeFiles":["docs/v2.0/concepts/errors.md"]},{"title":"Guides","description":"Trustap integration guides","includeFiles":["docs/v2.0/guides/**/*.md"],"excludeFiles":["docs/v2.0/guides/listing/"]},{"title":"API Reference","description":"Trustap API reference guide","includeFiles":["**/apis/@v2.0/openapi.yaml"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"upgrade-from-trustap-api-v1-to-api-v2","__idx":0},"children":["Upgrade from Trustap API v1 to API v2"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the following is a high level list to understand some of the fundamental changes to look out for."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-has-changed","__idx":1},"children":["What has changed"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"base-uris","__idx":2},"children":["Base URIs"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"API v1"},"children":["API v1"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"API v2"},"children":["API v2"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Sandbox"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://dev.stage.trustap.com/api/v1/"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.test.trustap.com/v2/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["Production"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://dev.trustap.com/api/v1/"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.trustap.com/v2/"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"flow-models","__idx":3},"children":["Flow models"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transaction-ids","__idx":4},"children":["Transaction IDs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"API v2","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API v2 transaction IDs are prefixed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tx_"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"JSON","data-title":"API v2 sample transaction ID","header":{"title":"API v2 sample transaction ID","controls":{"copy":{}}},"source":"    tx_01kq7pz74mffj9x5vsesqkve08\n","lang":"JSON"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"API v1","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"JSON","data-title":"API v1 sample transaction ID","header":{"title":"API v1 sample transaction ID","controls":{"copy":{}}},"source":"    346545\n","lang":"JSON"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transaction-objects","__idx":5},"children":["Transaction objects"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The transaction object has been redesigned."," ","Notable changes include the following."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Buyer and seller information is now grouped into nested objects."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pricing information is contained within a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pricing"]}," object."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Lifecycle timestamps are now available in an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["events"]}," object."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deadlines are grouped under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deadlines"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Transaction IDs are now prefixed strings."]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"API v2","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"JSON","data-title":"API v2 sample transaction object","header":{"title":"API v2 sample transaction object","controls":{"copy":{}}},"source":"    {\n    \"buyer\": {\n        \"id\": \"1-def29dfe-8626-48a2-8863-b6fdf2b96ff0\",\n        \"is_guest\": true\n    },\n    \"client_id\": \"5ad5451d-70c7-43c6-86c9-e1d90556856c\",\n    \"deadlines\": {\n        \"complaints\": null\n    },\n    \"description\": \"Trustap socks\",\n    \"events\": {\n        \"by_key\": {\n            \"created\": \"2026-04-27T14:54:51Z\",\n            \"joined\": \"2026-04-27T14:54:51Z\"\n        },\n        \"by_time\": [\n            {\n                \"at\": \"2026-04-27T14:54:51Z\",\n                \"code\": \"created\"\n            },\n            {\n                \"at\": \"2026-04-27T14:54:51Z\",\n                \"code\": \"joined\"\n            }\n        ]\n    },\n    \"id\": \"tx_01kq7pz74mffj9x5vsesqkve08\",\n    \"payment_link\": \"https://actions.stage.trustap.com/transactions/tx_01kq7pz74mffj9x5vsesqkve08/pay\",\n    \"pricing\": {\n        \"amount\": 20000,\n        \"amount_extra\": 0,\n        \"currency\": \"gbp\",\n        \"fees\": {\n            \"buyer\": 640,\n            \"buyer_client\": 0,\n            \"seller\": 0,\n            \"seller_client\": 0\n        }\n    },\n    \"seller\": {\n        \"id\": \"1-3f546125-2ec2-4b14-87f6-54a14ae73e98\",\n        \"is_guest\": true\n    },\n    \"status\": \"joined\"\n}\n","lang":"JSON"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"API v1","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"JSON","data-title":"API v1 sample transaction object","header":{"title":"API v1 sample transaction object","controls":{"copy":{}}},"source":"    {\n    \"buyer_id\": \"1-615a70d4-b624-4243-95be-a8367b7953ea\",\n    \"charge\": 720,\n    \"charge_seller\": 0,\n    \"client_id\": \"118931fb-e3fc-44fc-8a86-06a79d26972c\",\n    \"created\": \"2025-03-19T09:55:36Z\",\n    \"currency\": \"gbp\",\n    \"description\": \"Online no deposit\",\n    \"id\": 25439,\n    \"is_payment_in_progress\": false,\n    \"joined\": \"2025-03-19T09:55:36Z\",\n    \"price\": 20000,\n    \"quantity\": 1,\n    \"seller_id\": \"1-886e3c26-b585-4c92-a93b-e3c84b9b32e9\",\n    \"status\": \"joined\"\n    }\n","lang":"JSON"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webhooks","__idx":6},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API v2 introduces new webhook event codes and a redesigned payload format."," ","Changes include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Event codes now use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tx.*"]}," naming convention."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target_id"]}," now contains the new transaction ID format."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target_preview"]}," matches the new transaction object."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review the API v2 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/webhooks"},"children":["webhooks guide"]}," for more details."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"API v2","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"JSON","data-title":"API v2 sample webhook payload","header":{"title":"API v2 sample webhook payload","controls":{"copy":{}}},"source":"    {\n        \"code\": \"tx.paid\",\n        \"user_id\": \"1-0811c9c1-2a9b-4b06-ba7d-16b693f5c2b2\",\n        \"target_id\": \"tx_01kq9gj63sf4pbpesq9kna5ysa\",\n        \"target_preview\": {\n            \"buyer\": {\n            \"id\": \"1-0811c9c1-2a9b-4b06-ba7d-16b693f5c2b2\",\n            \"is_guest\": true\n            },\n            \"client_id\": \"e12c9fe5-bd07-47fd-81ec-263b6aaac8d6\",\n            \"deadlines\": {\n            \"complaints\": null\n            },\n            \"description\": \"v2 Payment\",\n            \"events\": {\n            \"by_key\": {\n                \"created\": \"2026-04-28T07:41:21Z\",\n                \"joined\": \"2026-04-28T07:41:21Z\",\n                \"paid\": \"2026-04-28T07:41:25Z\"\n            },\n            \"by_time\": [\n                {\n                \"at\": \"2026-04-28T07:41:21Z\",\n                \"code\": \"created\"\n                },\n                {\n                \"at\": \"2026-04-28T07:41:21Z\",\n                \"code\": \"joined\"\n                },\n                {\n                \"at\": \"2026-04-28T07:41:25Z\",\n                \"by\": \"1-0811c9c1-2a9b-4b06-ba7d-16b693f5c2b2\",\n                \"code\": \"paid\"\n                }\n            ]\n            },\n            \"id\": \"tx_01kq9gj63sf4pbpesq9kna5ysa\",\n            \"pricing\": {\n            \"amount\": 1000,\n            \"amount_extra\": 0,\n            \"currency\": \"eur\",\n            \"fees\": {\n                \"buyer\": 50,\n                \"buyer_client\": 0,\n                \"seller\": 0,\n                \"seller_client\": 0\n            }\n            },\n            \"seller\": {\n            \"id\": \"1-e2f0d161-41c7-429d-8cee-7e524e61756f\",\n            \"is_guest\": true\n            },\n            \"status\": \"paid\"\n        },\n        \"time\": \"2026-04-28T07:41:25.213691597Z\",\n        \"metadata\": {}\n        }\n","lang":"JSON"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"API v1","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"JSON","data-title":"API v1 sample webhook payload","header":{"title":"API v1 sample webhook payload","controls":{"copy":{}}},"source":"    {\n    \"code\": \"basic_tx.paid\",\n    \"user_id\": \"1-b7f83d35-37af-43df-acdd-851976179535\",\n    \"target_id\": \"32698\",\n    \"target_preview\": {\n        \"id\": 32698,\n        \"status\": \"paid\",\n        \"currency\": \"eur\",\n        \"quantity\": 1,\n        \"price\": 30000,\n        \"charge\": 130,\n        \"charge_seller\": 0,\n        \"charge_buyer_client\": 0,\n        \"charge_seller_client\": 0,\n        \"description\": \"Blue t-shirt with owl decal\",\n        \"created\": \"2026-02-11T12:40:54Z\",\n        \"is_payment_in_progress\": false,\n        \"client_id\": \"84a89340-6827-4f90-8cbd-f412ae72b5a7\",\n        \"buyer_id\": \"1-b7f83d35-37af-43df-acdd-851976179535\",\n        \"seller_id\": \"1-fdc6744b-e16d-48af-8b82-e4ffb4ae6168\",\n        \"joined\": \"2026-02-11T12:40:54Z\",\n        \"paid\": \"2026-02-11T12:42:13Z\",\n        \"tracking_details_window_started\": \"2026-02-11T12:42:13Z\",\n        \"tracking_details_deadline\": \"2026-02-11T12:42:13Z\"\n    },\n    \"time\": \"2026-02-11T12:42:13.161481114Z\",\n    \"metadata\": {}\n    }\n","lang":"JSON"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoints","__idx":7},"children":["Endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Endpoint paths have changed throughout API v2. Refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/openapi"},"children":["API reference"]}," when updating your integration."]}]},"headings":[{"value":"Upgrade from Trustap API v1 to API v2","id":"upgrade-from-trustap-api-v1-to-api-v2","depth":1},{"value":"What has changed","id":"what-has-changed","depth":2},{"value":"Base URIs","id":"base-uris","depth":3},{"value":"Flow models","id":"flow-models","depth":3},{"value":"Transaction IDs","id":"transaction-ids","depth":3},{"value":"Transaction objects","id":"transaction-objects","depth":3},{"value":"Webhooks","id":"webhooks","depth":3},{"value":"Endpoints","id":"endpoints","depth":3}],"frontmatter":{"seo":{"title":"Upgrade from Trustap API v1 to API v2","description":"Learn about difference between the Trustap API v1 and Trustap API v2."}},"lastModified":"2026-06-30T13:19:56.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/intro/upgrade","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}