# Online transaction flow The following steps show a full online transaction from start to finish. We show two types of flow. * Multiple sellers to multiple buyers. * A single seller to multiple buyers. Before you begin this guide, follow our [setup guide](/docs/intro/auth). ▦ Multiple sellers to multiple buyers ### Step 1: Create a guest seller For an application where you have different buyers and sellers, for example in a marketplace eCommerce solution, create guest buyers and guest sellers. * Every transaction must have two users, a seller and a buyer. * Using the Trustap API, guest buyers and sellers can complete a transaction together. To receive a payout, the seller must later create a full Trustap account. Create a guest seller ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/guest_users' \ --header 'Content-Type: application/json' \ --user ':' \ --data-raw '{"email":"sarah.garcia@shopit.com","first_name":"Sarah","last_name":"Garcia","country_code":"ie","tos_acceptance":{"unix_timestamp":1737558834,"ip":"127.0.0.1"}}' ``` Response ```JSON { "created_at": "2025-01-24T15:43:20.310247061Z", "email": "sarah.garcia@shopit.com", "id": "1-886e3c26-b585-4c92-a93b-e3c84b9b32e9" } ``` ### Step 2: Create a guest buyer The buyer is the party that receives the goods and pays for the transaction. Guest buyers can pay for transactions and even create complaints. Create a guest buyer ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/guest_users' \ --header 'Content-Type: application/json' \ --user ':' \ --data-raw '{"email":"bert.gray@my-mail.com","first_name":"Bert","last_name":"Gray","country_code":"ie","tos_acceptance":{"unix_timestamp":1737558834,"ip":"127.0.0.1"}}' ``` Response ```JSON { "created_at": "2025-01-24T15:43:20.310247061Z", "email": "bert.gray@my-mail.com", "id": "1-615a70d4-b624-4243-95be-a8367b7953ea" } ``` ### Step 3: Get Trustap Fee (Charge) Before creating a transaction, retrieve the charge for the transaction. This returns the cost for using the Trustap service for this transaction. `price` is an integer, in which the last 2 digits are the decimal part of the price. For example, `price:1050` `currency:eur` = 10,50€. When requesting bank transfer for payment, set `payment_method=bank_transfer` as a path parameter. For example, `https://dev.stage.trustap.com/api/v1/p2p/charge?price=20000¤cy=gbp&payment_method=bank_transfer`. If you don't set `payment_method` the Trustap API uses `card` as the default value. Get Trustap fee ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/charge?price=20000¤cy=gbp' \ --user ':' ``` Response ```json { "charge": 760, "charge_calculator_version": 3, "charge_config": 1, "charge_seller": 0, "currency": "gbp", "payment_method": "card", "price": 20000 } ``` ### Step 4: Create a transaction with a guest seller and guest buyer In the Trustap API, the transaction object includes details about the the buyer and seller, the type of transaction, and the status of the transaction. When requesting bank transfer for payment, set `"payment_method": "bank_transfer"`. If you don't set `payment_method` the Trustap API uses `card` as the default value. Create a transaction ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/me/transactions/create_with_guest_user' \ --header 'Trustap-User: 1-886e3c26-b585-4c92-a93b-e3c84b9b32e9' \ --header 'Content-Type: application/json' \ --user ':' \ --data '{ "seller_id": "1-886e3c26-b585-4c92-a93b-e3c84b9b32e9", "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "creator_role": "seller", "currency": "gbp", "description": "Ireland vs Croatia UEFA Nations League", "price": 20000, "charge": 760, "charge_calculator_version": 5, "image_url": "https://docs.trustap.com/images/soccer-tickets.png" }' ``` Response ```json { "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "charge": 760, "charge_seller": 0, "client_id": "118931fb-e3fc-44fc-8a86-06a79d26972c", "created": "2025-02-28T12:09:45Z", "currency": "gbp", "description": "Ireland vs Croatia UEFA Nations League", "id": 25273, "image_url": "https://docs.trustap.com/images/soccer-tickets.png", "is_payment_in_progress": false, "joined": "2025-02-28T12:09:45Z", "price": 20000, "quantity": 1, "seller_id": "1-886e3c26-b585-4c92-a93b-e3c84b9b32e9", "status": "joined" } ``` ### Step 5: Buyer transfers funds After a transaction is created, redirected the buyer to the payment page to pay for it. Trustap support two methods for payment. These funds will not be released to the seller until the buyer approves. #### Transfer using card With card transfer, direct the buyer using a URL to a payment screen where the buyer can enter their card details for secure payment. During testing, it's helpful to simulate the full payment flow. We recommend using [test credit card numbers](https://docs.stripe.com/testing) to complete transactions without processing real payments. #### Transfer using bank transfer With a bank transfer, direct your buyer using a URL to a screen displaying bank transfer details. Card payment The payment URL that you send to the buyer depends on your type of integration. In the following examples, replace `` with the redirect URI you set [during your Trustap setup](/docs/intro/auth). This is the location where the buyer will be redirected to following payment. ##### Test environment - Guest buyer ``` https://actions.stage.trustap.com/online/transactions/{transaction_id}/guest_pay?redirect_uri= ``` ##### Test environment - Full user buyer ``` https://actions.stage.trustap.com/online/transactions/{transaction_id}/pay?redirect_uri= ``` ##### Production environment - Guest buyer ``` https://actions.trustap.com/online/transactions/{transaction_id}/guest_pay? ``` ##### Production environment - Full user buyer ``` https://actions.trustap.com/online/transactions/{transaction_id}/pay? ``` For example: ```cURL https://actions.stage.trustap.com/online/transactions/25273/guest_pay?redirect_uri=https://www.example.com ``` The Trustap API also supports `state` when sending a buyer to the payment screen. Learn more about `state` in our [guide](/docs/guides/state). The payment screen looks like the following. Image with dimensions Bank transfer Ensure, you have following configured. * **Step 3** to include `payment_method=bank_transfer`. * **Step 4** to include `"payment_method": "bank_transfer"`. Guide your buyer to pay using the [Trustap payment screen](#payment=card&flow=single). Bank transfer payment screen Instead of card payment details, your buyer will be shown bank transfer details after they submit their personal details. Bank transfer details Alternatively, you can use the [bank details endpoint](/apis/openapi#online-payment/basic%2Egetbanktransferdetails). ```CURL Get the bank details curl --location 'https://dev.stage.trustap.com/api/v1/transactions/{transaction_id}/bank_transfer_details' \ --user ':' ``` The response includes all the details needed for a buyer to complete the transaction over a bank transfer. Use the `hosted_instructions_url` to share instructions on how to use the bank details. ```JSON Bank details response { "amount": 0, "currency": "string", "financial_address": { "aba": { "account_number": "string", "bank_name": "string", "routing_number": "string" }, "iban": { "account_holder_name": "string", "bic": "string", "country": "string", "iban": "string" }, "sort_code": { "account_holder_name": "string", "account_number": "string", "sort_code": "string" }, "swift": { "account_number": "string", "bank_name": "string", "swift_code": "string" } }, "hosted_instructions_url": "string", "reference": "string" } ``` ### Step 6: Seller adds tracking details When the seller has arranged delivery, they add the tracking details to the transaction. The Trustap API also supports an integrated shipping solution. See our [Shipping](/docs/guides/transactions/online/online-shipping) guide for more information. Seller adds tracking ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/transactions/25273/track_with_guest_seller' \ --header 'Trustap-User: 1-886e3c26-b585-4c92-a93b-e3c84b9b32e9' \ --header 'Content-Type: application/json' \ --user ':' \ --data '{ "carrier": "ups", "tracking_code": "345345123" }' ``` Response ```JSON { "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "charge": 760, "charge_seller": 0, "client_id": "118931fb-e3fc-44fc-8a86-06a79d26972c", "created": "2025-02-28T12:09:45Z", "currency": "gbp", "description": "Ireland vs Croatia UEFA Nations League", "id": 25273, "image_url": "https://docs.trustap.com/images/soccer-tickets.png", "is_payment_in_progress": false, "joined": "2025-02-28T12:09:45Z", "price": 20000, "quantity": 1, "seller_id": "1-886e3c26-b585-4c92-a93b-e3c84b9b32e9", "status": "tracked", "tracked": "2025-02-29T12:00:00Z", "tracking": { "carrier": "ups", "tracking_code": "345345123" }, "tracking_details_deadline": "2025-03-04T14:14:34Z", "tracking_details_window_started": "2025-02-28T14:14:34Z" } ``` ### Step 7: Buyer confirms delivery (optional) Once the item has been delivered, the buyer must confirm the delivery was complete before funds can be released to the seller. The complaints period begins (24h) when any of the users confirms the delivery. Buyer confirms delivery ```CURL curl --location --request POST 'https://dev.stage.trustap.com/api/v1/transactions/25273/confirm_delivery_with_guest_buyer' \ --header 'Trustap-User: 1-886e3c26-b585-4c92-a93b-e3c84b9b32e9' \ --user ':' ``` Response ```JSON { "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "charge": 760, "charge_international_payment": 311, "charge_seller": 0, "client_id": "118931fb-e3fc-44fc-8a86-06a79d26972c", "complaint_period_deadline": "2025-02-28T14:21:54Z", "created": "2025-02-28T14:12:15Z", "currency": "gbp", "delivered": "2025-02-28T14:16:54Z", "description": "Ireland vs Croatia UEFA Nations League", "id": 25273, "image_url": "https://docs.trustap.com/images/soccer-tickets.png", "is_payment_in_progress": false, "joined": "2025-02-28T14:12:15Z", "paid": "2025-02-28T14:14:34Z", "price": 20000, "quantity": 1, "seller_id": "1-886e3c26-b585-4c92-a93b-e3c84b9b32e9", "status": "delivered", "tracked": "2025-02-28T14:15:18Z", "tracking": { "carrier": "ups", "tracking_code": "345345123" }, "tracking_details_deadline": "2025-03-04T14:14:34Z", "tracking_details_window_started": "2025-02-28T14:14:34Z" } ``` ### Step 8: Complaints period (optional) At this point, the buyer has an option to create a complaint. This means that were not satisfied with the transaction. A complaint will pause any payout until the dispute has been resolved. See our guide to [create a complaint](/docs/guides/transactions/complaint). ### Step 9: Seller claims payout Before a seller can claim, they must create a full Trustap account from a guest to a full user account. See our [full user guide](/docs/guides/transactions/full-users) for details. Following confirmation of delivery, the seller can claim the payout. Claiming the payout means the seller requests to receive the money for the transaction. Seller claims payout ```CURL curl --location --request POST 'https://dev.stage.trustap.com/api/v1/transactions/25273/claim_for_seller' \ --header 'Trustap-User: b9c9e108-1edd-5d5e-8268-8873d7beb3e3' \ --user ':' ``` Response ```JSON { } ``` ▣ Single seller to multiple buyers ### Step 1: Create a full user for your seller If you do not have an existing seller `id`, [create a full user](/docs/guides/transactions/full-users). If you previously created a full user for this seller, [retrieve this stored](/docs/guides/transactions/full-users#step-4-store-the-trustap-full-user-id) `id`. Use this id for `seller_id`. You can identify full users from guest users by looking at their `id`. A guest user `id` will always begin with `1-`. For example `1-615a70d4-b624-4243-95be-a8367b7953ea`. ### Step 2: Create a guest buyer The buyer is the party that receives the goods and pays for the transaction. Guest buyers can pay for transactions and even create complaints. Create a guest buyer ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/guest_users' \ --header 'Content-Type: application/json' \ --user ':' \ --data-raw '{"email":"bert.gray@my-mail.com","first_name":"Bert","last_name":"Gray","country_code":"ie","tos_acceptance":{"unix_timestamp":1737558834,"ip":"127.0.0.1"}}' ``` Response ```JSON { "created_at": "2025-01-24T15:43:20.310247061Z", "email": "bert.gray@my-mail.com", "id": "1-615a70d4-b624-4243-95be-a8367b7953ea" } ``` ### Step 3: Get Trustap Fee (Charge) Before creating a transaction, retrieve the charge for the transaction. This returns the cost for using the Trustap service for this transaction. `price` is an integer, in which the last 2 digits are the decimal part of the price. For example, `price:1050` `currency:eur` = 10,50€. When requesting bank transfer for payment, set `payment_method=bank_transfer` as a path parameter. For example, `https://dev.stage.trustap.com/api/v1/p2p/charge?price=20000¤cy=gbp&payment_method=bank_transfer`. If you don't set `payment_method` the Trustap API uses `card` as the default value. Get Trustap fee ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/charge?price=20000¤cy=gbp' \ --user ':' ``` Response ```json { "charge": 760, "charge_calculator_version": 3, "charge_config": 1, "charge_seller": 0, "currency": "gbp", "payment_method": "card", "price": 20000 } ``` ### Step 4: Create a transaction with a seller and guest buyer In the Trustap API, the transaction object includes details about the the buyer and seller, the type of transaction, and the status of the transaction. When requesting bank transfer for payment, set `"payment_method": "bank_transfer"`. If you don't set `payment_method` the Trustap API uses `card` as the default value. Create a transaction ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/me/transactions/create_with_guest_user' \ --header 'Trustap-User: b9c9e108-1edd-5d5e-8268-8873d7beb3e3' \ --header 'Content-Type: application/json' \ --user ':' \ --data '{ "seller_id": "b9c9e108-1edd-5d5e-8268-8873d7beb3e3", "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "creator_role": "seller", "currency": "gbp", "description": "Ireland vs Croatia UEFA Nations League", "price": 20000, "charge": 760, "charge_calculator_version": 5, "image_url": "https://docs.trustap.com/images/soccer-tickets.png" }' ``` Response ```json { "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "charge": 760, "charge_seller": 0, "client_id": "118931fb-e3fc-44fc-8a86-06a79d26972c", "created": "2025-02-28T12:09:45Z", "currency": "gbp", "description": "Ireland vs Croatia UEFA Nations League", "id": 25273, "image_url": "https://docs.trustap.com/images/soccer-tickets.png", "is_payment_in_progress": false, "joined": "2025-02-28T12:09:45Z", "price": 20000, "quantity": 1, "seller_id": "b9c9e108-1edd-5d5e-8268-8873d7beb3e3", "status": "joined" } ``` ### Step 5: Buyer transfers funds After a transaction is created, redirect the buyer to the payment page to pay for it. Trustap support two methods for payment. These funds will not be released to the seller until the buyer approves. #### Transfer using card With card transfer, direct the buyer using a URL a payment screen where the buyer can enter their card details for secure payment. During testing, it's helpful to simulate the full payment flow. We recommend using [test credit card numbers](https://docs.stripe.com/testing) to complete transactions without processing real payments. #### Transfer using bank transfer With a bank transfer, direct the buyer using a URL to a screen displaying bank transfer details. Card payment The payment URL that you send to the buyer depends on your type of integration. In the following examples, replace `` with the redirect URI you set [during your Trustap setup](/docs/intro/auth). This is the location where the buyer will be redirected to following payment. ##### Test environment - Guest buyer ``` https://actions.stage.trustap.com/online/transactions/{transaction_id}/guest_pay?redirect_uri= ``` ##### Test environment - Full user buyer ``` https://actions.stage.trustap.com/online/transactions/{transaction_id}/pay?redirect_uri= ``` ##### Production environment - Guest buyer ``` https://actions.trustap.com/online/transactions/{transaction_id}/guest_pay? ``` ##### Production environment - Full user buyer ``` https://actions.trustap.com/online/transactions/{transaction_id}/pay? ``` For example: ```cURL https://actions.stage.trustap.com/online/transactions/25273/guest_pay?redirect_uri=https://www.example.com ``` The Trustap API also supports `state` when sending a buyer to the payment screen. Learn more about `state` in our [guide](/docs/guides/state). The payment screen looks like the following. Image with dimensions Bank transfer Ensure, you have following configured. * **Step 3** to include `payment_method=bank_transfer`. * **Step 4** to include `"payment_method": "bank_transfer"`. Guide your buyer to pay using the [Trustap payment screen](#payment=card&flow=multiple). Bank transfer payment screen Instead of card payment details, your buyer will be shown bank transfer details after they submit their personal details. Bank transfer details Alternatively, you can use the [bank details endpoint](/apis/openapi#online-payment/basic%2Egetbanktransferdetails). ```CURL Get the bank details curl --location 'https://dev.stage.trustap.com/api/v1/transactions/{transaction_id}/bank_transfer_details' \ --user ':' ``` The response includes all the details needed for a buyer to complete the transaction over a bank transfer. Use the `hosted_instructions_url` to share instructions on how to use the bank details. ```JSON Bank details response { "amount": 0, "currency": "string", "financial_address": { "aba": { "account_number": "string", "bank_name": "string", "routing_number": "string" }, "iban": { "account_holder_name": "string", "bic": "string", "country": "string", "iban": "string" }, "sort_code": { "account_holder_name": "string", "account_number": "string", "sort_code": "string" }, "swift": { "account_number": "string", "bank_name": "string", "swift_code": "string" } }, "hosted_instructions_url": "string", "reference": "string" } ``` ### Step 6: Seller adds tracking details When the seller has arranged delivery, they add the tracking details to the transaction. [Full Trustap users](/docs/guides/transactions/full-users#scopes) must include the scope `basic_tx.offline_track`. The Trustap API also supports an integrated shipping solution. See our [Shipping](/docs/guides/transactions/online/online-shipping) guide for more information. Seller adds tracking ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/transactions/25273/track' \ --header 'Content-Type: application/json' \ --header 'Trustap-User: b9c9e108-1edd-5d5e-8268-8873d7beb3e3' \ --user ':' \ --data '{ "carrier": "ups", "tracking_code": "345345123" }' ``` Response ```JSON { "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "charge": 760, "charge_seller": 0, "client_id": "118931fb-e3fc-44fc-8a86-06a79d26972c", "created": "2025-02-28T12:09:45Z", "currency": "gbp", "description": "Ireland vs Croatia UEFA Nations League", "id": 25273, "image_url": "https://docs.trustap.com/images/soccer-tickets.png", "is_payment_in_progress": false, "joined": "2025-02-28T12:09:45Z", "price": 20000, "quantity": 1, "seller_id": "b9c9e108-1edd-5d5e-8268-8873d7beb3e3", "status": "tracked", "tracked": "2025-02-29T12:00:00Z", "tracking": { "carrier": "ups", "tracking_code": "345345123" }, "tracking_details_deadline": "2025-03-04T14:14:34Z", "tracking_details_window_started": "2025-02-28T14:14:34Z" } ``` ### Step 7: Buyer confirms delivery (optional) Once the item has been delivered, the buyer must confirm the delivery was complete before funds can be released to the seller. The complaints period begins (24h) when any of the users confirms the delivery. Buyer confirms delivery ```CURL curl --location --request POST 'https://dev.stage.trustap.com/api/v1/transactions/25273/confirm_delivery_with_guest_buyer' \ --header 'Trustap-User: 1-886e3c26-b585-4c92-a93b-e3c84b9b32e9' \ --user ':' ``` Response ```JSON { "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "charge": 760, "charge_international_payment": 311, "charge_seller": 0, "client_id": "118931fb-e3fc-44fc-8a86-06a79d26972c", "complaint_period_deadline": "2025-02-28T14:21:54Z", "created": "2025-02-28T14:12:15Z", "currency": "gbp", "delivered": "2025-02-28T14:16:54Z", "description": "Ireland vs Croatia UEFA Nations League", "id": 25273, "image_url": "https://docs.trustap.com/images/soccer-tickets.png", "is_payment_in_progress": false, "joined": "2025-02-28T14:12:15Z", "paid": "2025-02-28T14:14:34Z", "price": 20000, "quantity": 1, "seller_id": "b9c9e108-1edd-5d5e-8268-8873d7beb3e3", "status": "delivered", "tracked": "2025-02-28T14:15:18Z", "tracking": { "carrier": "ups", "tracking_code": "345345123" }, "tracking_details_deadline": "2025-03-04T14:14:34Z", "tracking_details_window_started": "2025-02-28T14:14:34Z" } ``` ### Step 8: Complaints period (optional) At this point, the buyer has an option to create a complaint. This means that were not satisfied with the transaction. A complaint will pause any payout until the dispute has been resolved. See our guide to [create a complaint](/docs/guides/transactions/complaint). ### Step 9: Payout Following the complaints period and successful resolution of any complaints, the seller receives the payout to their account. The seller automatically receives their payout only if they have completed their payout details in their Trustap profile.