{"templateId":"markdown","versions":[{"version":"v1.0","label":"v1.0","link":"/docs/v1.0/guides/transactions/transaction-lifecycle","default":false,"active":false,"folderId":"a2557b8d"},{"version":"v2.0","label":"v2.0 (latest version)","link":"/docs/guides/transactions/transaction-lifecycle","default":true,"active":true,"folderId":"a2557b8d"}],"sharedDataIds":{"sidebar":"sidebar-docs/@v1.0/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab","TransactionTubeMapWrapper"]},"type":"markdown"},"seo":{"title":"Transaction lifecycle","description":"Guide to transaction lifecycle showing how the transaction status changes during the  life of the transaction.","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":"transaction-lifecycle","__idx":0},"children":["Transaction lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every transaction has a lifecycle where it moves from one state to another. Depending on the state, users can perform different actions. Usually, there is one action which moves the transaction further and one action for cancelling the transaction. If the transaction is cancelled and there is payment, the buyer gets refunded automatically (usually within 1 hour)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The status of a transaction is stored in the transaction object."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Transaction status","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"cURL","header":{"controls":{"copy":{}}},"source":"  curl -i -X GET \\\n    -u '<API_KEY>:' \\\n    'https://api.test.trustap.com/v2/transactions/{transaction_id}'\n","lang":"cURL"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Response","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"JSON","header":{"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-05-07T15:39:46Z\",\n        \"joined\": \"2026-05-07T15:39:46Z\"\n      },\n      \"by_time\": [\n        {\n          \"at\": \"2026-05-07T15:39:46Z\",\n          \"code\": \"created\"\n        },\n        {\n          \"at\": \"2026-05-07T15:39:46Z\",\n          \"code\": \"joined\"\n        }\n      ]\n    },\n    \"id\": \"tx_01kr1hgnqred6999kp7cqmx8ss\",\n    \"payment_link\": \"https://actions.stage.trustap.com/transactions/tx_01kr1hgnqred6999kp7cqmx8ss/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":"Heading","attributes":{"level":2,"id":"interactive-status-transition-map","__idx":1},"children":["Interactive status transition map"]},{"$$mdtype":"Tag","name":"TransactionTubeMapWrapper","attributes":{"nodes":[{"id":"created","label":"created","x":50,"y":150},{"id":"joined","label":"joined","x":150,"y":150},{"id":"cancelled","label":"cancelled","x":350,"y":250},{"id":"refunded","label":"refunded","x":650,"y":250},{"id":"paid","label":"paid","x":250,"y":150},{"id":"payment_accepted","label":"payment_accepted","x":350,"y":150,"rotation":15},{"id":"tracked","label":"tracked","x":465,"y":150,"rotation":-15},{"id":"delivered","label":"delivered","x":555,"y":150,"rotation":-15},{"id":"seller_handover_confirmed","label":"seller_handover_confirmed","x":540,"y":100,"rotation":0},{"id":"buyer_handover_confirmed","label":"buyer_handover_confirmed","x":525,"y":50,"rotation":0},{"id":"complaint_submitted","label":"complaint_submitted","x":650,"y":210,"rotation":0},{"id":"complaint_period_ended","label":"complaint_period_ended","x":670,"y":150,"rotation":-15},{"id":"funds_released","label":"funds_released","x":770,"y":150,"rotation":-15}],"idealPath":["created","joined","paid","payment_accepted","tracked","delivered","complaint_period_ended","funds_released"],"links":[{"from":"created","to":"joined","who":"buyer/seller","waypoints":[]},{"from":"created","to":"cancelled","who":"buyer/seller","waypoints":[{"x":50,"y":280},{"x":350,"y":280}]},{"from":"paid","to":"cancelled","who":"buyer/seller","waypoints":[{"x":250,"y":220},{"x":350,"y":220}]},{"from":"cancelled","to":"refunded","who":"trustap","waypoints":[]},{"from":"joined","to":"paid","who":"buyer","waypoints":[]},{"from":"joined","to":"cancelled","who":"buyer/seller","waypoints":[{"x":150,"y":250}]},{"from":"paid","to":"payment_accepted","who":"seller","waypoints":[]},{"from":"payment_accepted","to":"tracked","who":"seller","waypoints":[]},{"from":"tracked","to":"delivered","who":"seller","waypoints":[]},{"from":"payment_accepted","to":"buyer_handover_confirmed","who":"buyer","waypoints":[{"x":350,"y":50}]},{"from":"payment_accepted","to":"seller_handover_confirmed","who":"seller","waypoints":[{"x":350,"y":100}]},{"from":"delivered","to":"complaint_submitted","who":"buyer","waypoints":[{"x":555,"y":210}]},{"from":"delivered","to":"complaint_period_ended","who":"trustap","waypoints":[]},{"from":"buyer_handover_confirmed","to":"complaint_submitted","who":"buyer","waypoints":[{"x":525,"y":210}]},{"from":"buyer_handover_confirmed","to":"complaint_period_ended","who":"trustap","waypoints":[{"x":670,"y":50}]},{"from":"seller_handover_confirmed","to":"complaint_submitted","who":"seller","waypoints":[{"x":540,"y":210}]},{"from":"seller_handover_confirmed","to":"complaint_period_ended","who":"trustap","waypoints":[{"x":670,"y":100},{"x":670,"y":115}]},{"from":"complaint_period_ended","to":"funds_released","who":"trustap","waypoints":[]},{"from":"complaint_submitted","to":"funds_released","who":"trustap","waypoints":[{"x":725,"y":210},{"x":725,"y":150}]},{"from":"complaint_submitted","to":"refunded","who":"trustap","waypoints":[]},{"from":"payment_accepted","to":"cancelled","who":"trustap","waypoints":[]}]},"children":[]},{"$$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":{"width":"30%","data-label":"Status"},"children":["Status "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Next possible status"},"children":["Next possible status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Transitions"},"children":["Transitions"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"created"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transactions start off in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created"]}," state, and will have either a \"seller\" or a \"buyer\" user (the user who created the transaction) linked to it."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["joined"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A Trustap user other than the creator can join a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created"]}," transaction. The creator of the transaction can cancel a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created"]}," transaction using its id."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"joined"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["joined"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["joined"]}," transaction is one that has both a seller and a buyer user linked to it, and requires payment before moving on to the next state."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The buyer can pay a deposit for, or cancel, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["joined"]}," transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"paid"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]}," transaction is one where a buyer has paid for a transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_accepted"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"cancelled"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}," transaction is a transaction where one of the buyer or seller has decided not to continue the transaction. A cancelled transaction is considered to be completed in most transactions. If a transaction has been ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]},", then the transaction will from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"payment_accepted"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_accepted"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_accepted"]}," transaction waits for the seller to set the pricing for the transaction before progressing."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tracked"]},",",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buyer_handover_confirmed"]},",",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buyer_handover_confirmed"]},",",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Accept a deposit for, or cancel, a paid transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"tracked"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tracked"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tracked"]}," transaction has received a tracking tracking number from a seller."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivered"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"cancelled"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}," transaction is one that has been cancelled after its deposit has been paid."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Trustap platform updates the state of a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}," transaction to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}," once the deposit has been refunded to the buyer."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"refunded"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}," transaction is considered to be completed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["–"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"delivered"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivered"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivered"]}," transaction is one that has been confirmed that have been delivered to a buyer."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complained"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complaint_period_ended"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The buyer can complain about a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buyer_handover_confirmed"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["seller_handover_confirmed"]}," transaction before the complaints period ends."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The seller can confirm the handover of the goods."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"seller_handover_confirmed"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["seller_handover_confirmed"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["seller_handover_confirmed"]}," transaction gives the seller an opportunity to verify the item they have received. Once the item has been received, the Trustap platform begins a \"complaints period\"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complained"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complaint_period_ended"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The buyer can complain about a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buyer_handover_confirmed"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["seller_handover_confirmed"]}," transaction before the complaints period ends."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If no such complaint occurs before the complaints period ends then the Trustap platform will release the funds for the transaction to the seller and will update the state to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["funds_released"]},"."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"seller_handover_confirmed"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buyer_handover_confirmed"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buyer_handover_confirmed"]}," transaction gives the buyer an opportunity to verify the item they have received. Once the item has been received, the Trustap platform begins a \"complaints period\"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complained"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complaint_period_ended"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The buyer can complain about a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buyer_handover_confirmed"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["seller_handover_confirmed"]}," transaction before the complaints period ends."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If no such complaint occurs before the complaints period ends then the Trustap platform will release the funds for the transaction to the seller and will update the state to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["funds_released"]},"."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"complained"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complaint_submitted"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complaint_submitted"]}," transaction is registered with Trustap for conflict resolution."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["funds_released"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["After arbitration, Trustap will release the funds to the buyer and/or seller in a certain ratio and will update the state to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["funds_released"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"funds_released"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["funds_released"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["funds_released"]}," transaction is considered to be completed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["–"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"id":"complaint_period_ended"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complaint_period_ended"]}," "]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The time window to file a complaint has ended."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["funds_released_released"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]}]}]}]}]},"headings":[{"value":"Transaction lifecycle","id":"transaction-lifecycle","depth":1},{"value":"Interactive status transition map","id":"interactive-status-transition-map","depth":2}],"frontmatter":{"breadcrumbs":{"hide":true},"markdown":{"toc":{"hide":true}},"seo":{"title":"Transaction lifecycle","description":"Guide to transaction lifecycle showing how the transaction status changes during the  life of the transaction."}},"lastModified":"2026-06-18T11:39:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/guides/transactions/transaction-lifecycle","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}