# Online integrated shipping You can use the Trustap API to generate and purchase shipping labels. Trustap uses [Shippo](https://www.goshippo.com) to generate shipping labels. These shipping labels can be printed by sellers, attached to parcels, and used to transport items to a buyer. Use the following flow to add shipping to an [online transaction](/docs/guides/transactions/online/online-int-path). ## Step 1: Create buyers, sellers, and calculate charges ▦ Multiple sellers to multiple buyers 1. Create a [guest seller](/docs/guides/transactions/online/online-int-path#step-1-create-a-guest-seller) (`seller_id`) 2. Create a [guest buyer](/docs/guides/transactions/online/online-int-path#step-2-create-a-guest-buyer) (`buyer_id`) 3. [Calculate charges](/docs/guides/transactions/online/online-int-path#step-3-get-trustap-fee-charge) ▣ Single seller to multiple buyers 1. Get your [seller ID](/docs/guides/transactions/online/online-int-path#step-1-get-your-seller-id) (`seller_id`) 2. Create a [guest buyer](/docs/guides/transactions/online/online-int-path#step-2-create-a-guest-buyer) (`buyer_id`) 3. [Calculate charges](/docs/guides/transactions/online/online-int-path#step-3-get-trustap-fee-charge) ## Step 2: Create a transaction To enable shipping for a transaction, include `use_shippo` and `require_seller_acceptance` in `features` when creating the transaction. ```CURL "features": ["use_shippo", "require_seller_acceptance"] ``` Create transaction including shipping ```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": "Online no deposit", "price": 20000, "charge": 720, "charge_calculator_version": 5, "features": ["use_shippo", "require_seller_acceptance"] }' ``` Response ```JSON { "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" } ``` ## Step 3: Add sender address Add your sender`s address. To receive an accurate shipping rate estimation, it is important to use an accurate address. For `country`, use [ISO 3166-1 alpha-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Add sender address ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/transactions/25439/shippo_address' \ --user ':' \ --header 'Content-Type: application/json' \ --data '{ "city": "London", "country": "GB", "full_name": "Sarah Garcia", "phone": "4215559099", "state": "London", "street_1": "12 Abercrombie Rd", "zip_code": "E20 3AB", "is_sender_address": true }' ``` Response ```JSON { "city": "London", "country": "GB", "full_name": "Sarah Garcia", "phone": "4215559099", "state": "London", "street_1": "12 Abercrombie Rd", "zip_code":"E20 3AB" } ``` ## Step 4: Add recipient address Add your recipient`s address. It is important to use an accurate address to avoid issues in shipping rate estimation and parcel delivery. For `country`, use [ISO 3166-1 alpha-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Add recipient address ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/transactions/25439/shippo_address' \ --user ':' \ --header 'Content-Type: application/json' \ --data '{ "city": "Manchester", "country": "GB", "full_name": "Bert Gray", "phone": "123456789", "zip_code": "M11 4DQ", "state": "Manchester", "street_1": "42 Stuart St", "is_sender_address": false }' ``` Response ```JSON { "city": "Manchester", "country": "GB", "full_name": "Bert Gray", "phone": "123456789", "zip_code":"M11 4DQ", "state": "Manchester", "street_1": "42 Stuart St" } ``` ## Step 5: Add parcel details Add parcel details. These are the physical characteristics of your parcel. It's important to use accurate parcel details as they are used to determine the most appropriate shipping options for your parcel. Add parcel details ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/transactions/25439/shippo_parcel_details' \ --user ':' \ --header 'Content-Type: application/json' \ --data '{ "distance_unit": "cm", "height": 10, "length": 10, "mass_unit": "lb", "weight": 10, "width": 10, "shipment_date": "2025-11-18T00:35:03.463Z" }' ``` Response ```JSON { "distance_unit": "cm", "height": 10, "lenght": 10, "mass_unit": "lb", "weight": 10, "width": 10, "shipment_date": "2025-11-18T00:35:03.463Z" } ``` ## Step 6: Declare customs for shipment A customs declaration is a record of the details about the contents of a parcel. For international shipping, this is required. It ensures compliance with import and export regulations and helps determine duties, taxes, and restrictions. Add customs details ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/transactions/25439/shippo_customs_declaration' \ --user ':' \ --header 'Content-Type: application/json' \ --data '{ "certify": true, "certify_signer": "Bert Gray", "description": "T-Shirt", "incoterm": "DDU", "mass_unit": "lb", "net_weight": 10, "non_delivery_option": "return", "origin_country": "GB", "quantity": 1, "value_amount": "200", "value_currency": "GBP" }' ``` Response For international shipments, the customs details are added to the shipment. These are printed on the label where appropriate. This example is shipment within the UK so a customs declaration is not required. The follow response is expected when a customs declaration is not required. ```JSON { "code": "nothing_to_declare", "error": "sender's and recipient's address are within the same custom union area" } ``` ## Step 7: Find shipping options Find shipping rates available to ship the seller's parcel. Request shipping rates ```CURL curl --location 'https://dev.stage.trustap.com/api/v1/transactions/25439/shippo_shipping_rates' \ --user ':' ``` Response ```JSON [ { "amount": "6.14", "amount_local": "6.14", "attributes": [], "currency": "GBP", "currency_local": "GBP", "duration_terms": "", "estimated_days": 0, "id": "1621f20647db4bc1a1b8ba9297b64305", "provider": "Hermes UK", "provider_image": "https://shippo-static.s3.amazonaws.com/providers/200/myHermes.png" }, { "amount": "5.27", "amount_local": "5.27", "attributes": [ "CHEAPEST" ], "currency": "GBP", "currency_local": "GBP", "duration_terms": "", "estimated_days": 0, "id": "417bb46e734c457e97316122081cf99f", "provider": "Hermes UK", "provider_image": "https://shippo-static.s3.amazonaws.com/providers/200/myHermes.png" }, { "amount": "5.38", "amount_local": "5.38", "attributes": [], "currency": "GBP", "currency_local": "GBP", "duration_terms": "", "estimated_days": 0, "id": "81a9a7ed99bc4f508a4edba72e51dee6", "provider": "DPD UK", "provider_image": "https://shippo-static.s3.amazonaws.com/providers/200/DPD.png" } ] ``` ## Step 8: Select shipping option and add to transaction Select a rate returned from `shippo_shipping_rates` using the `id` of your preferred rate. Add shipping rate to transaction ```CURL curl --location --globoff 'https://dev.stage.trustap.com/api/v1/transactions/25439/shippo_shipping_rate' \ --header 'Trustap-User: 1-886e3c26-b585-4c92-a93b-e3c84b9b32e9' \ --header 'Content-Type: application/json' \ --user ':'\ --data '{ "rate_id": "417bb46e734c457e97316122081cf99f" }' ``` Response 204 ## Step 9: Buyer transfers funds After a transaction is created, the buyer should be redirected to the payment page to pay for it. The cost of the transaction includes both the Trustap fee and shipping fee. 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 | Production environment | | --- | --- | --- | | Guest buyer | `https://actions.stage.trustap.com/online/transactions/{transaction_id}/guest_pay?redirect_uri= ` | `https: //actions.trustap.com/online/transactions/{transaction_id}/guest_pay? ` | | Full user buyer | `https: //actions.stage.trustap.com/online/transactions/{transaction_id}/pay?redirect_uri= ` | `https://actions.trustap.com/online/transactions/{transaction_id}/pay? ` | For example: ```cURL https://actions.stage.trustap.com/online/transactions/25439/guest_pay?redirect_uri=https://www.example.com ``` The payment screen looks like the following. ![](/assets/online-payment-shipping.3337973a4d65a06de46d1bd09e4c2150591a39bcb13498735e0a8dcf56f3ce93.afd4d3cf.png) Bank transfer ```CURL 1. Set payment method to bank transfer curl --location 'https://dev.stage.trustap.com/api/v1/transactions/{transaction_id}/set_payment_method' \ --user ':' \ --header 'Content-Type: application/json' \ --data '{ "currency": "gbp", "charge": 760, "charge_seller": 0, "price": 20000, "payment_method": "bank_transfer" }' ``` ```CURL 2. 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" } ``` There is another option for displaying account details. To display an option for card payment or bank transfer follow these steps. 1. Set payment method to bank transfer as above. 2. Follow the steps in card payment. When the buyer is directed to the card payment screen, they will see the option for card payment or bank transfer. ## Step 10: Seller accepts payment The seller must accept the payment. At this point, the shipping label is purchased. Accept payment for seller ```CURL curl --location --globoff --request POST 'https://dev.stage.trustap.com/api/v1/transactions/25439/accept_payment_with_guest_seller' \ --header 'Trustap-User: 1-886e3c26-b585-4c92-a93b-e3c84b9b32e9' \ --user ':' ``` Response ```JSON { "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "charge": 720, "charge_postage_buyer": 527, "charge_postage_client": 0, "charge_seller": 0, "client_id": "118931fb-e3fc-44fc-8a86-06a79d26972c", "created": "2025-03-19T10:37:48Z", "currency": "gbp", "description": "Online no deposit", "id": 25439, "is_payment_in_progress": false, "joined": "2025-03-19T10:37:48Z", "paid": "2025-03-19T10:47:03Z", "payment_accepted": "2025-03-19T10:51:02Z", "price": 20000, "quantity": 1, "seller_id": "1-886e3c26-b585-4c92-a93b-e3c84b9b32e9", "status": "tracked", "tracked": "2025-03-19T10:51:04Z", "tracking": { "carrier": "Hermes UK", "tracking_code": "P1234567890123456" }, "tracking_details_deadline": "2025-03-23T10:51:02Z", "tracking_details_window_started": "2025-03-19T10:51:02Z" } ``` ## Step 11: Get Shipping label The shipping label is available to download, print, and attach to the parcel using `label_url`. Tracking details are also available through `tracking_code` and `tracking_url`. Get Shipping label ```CURL curl --location --globoff 'https://dev.stage.trustap.com/api/v1/transactions/25372/shippo_shipping_label' \ --header 'Trustap-User: 1-615a70d4-b624-4243-95be-a8367b7953ea' \ --user ':' ``` Response ```JSON { "label_url": "https://shippo-delivery.s3.amazonaws.com/96.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA", "tracking_code": "P1234567890123456", "tracking_url": "https://www.evri.com/track/parcel/P1234567890123456" } ``` ## Step 12: Delivery to buyer is confirmed When the Trustap API receives confirmation from the carrier that the parcel has been delivered, delivery will automatically be confirmed. Optionally, the buyer or the seller can manually confirm delivery. Buyer confirms delivery ```CURL curl --location --globoff --request POST 'https://dev.stage.trustap.com/api/v1/transactions/25372/confirm_delivery_with_guest_buyer' \ --header 'Trustap-User: 1-615a70d4-b624-4243-95be-a8367b7953ea' \ --user ':' \ ``` Response ```JSON { "buyer_id": "1-615a70d4-b624-4243-95be-a8367b7953ea", "charge": 720, "charge_postage_buyer": 527, "charge_postage_client": 0, "charge_seller": 0, "client_id": "118931fb-e3fc-44fc-8a86-06a79d26972c", "complaint_period_deadline": "2025-03-19T11:01:35Z", "created": "2025-03-19T10:37:48Z", "currency": "gbp", "delivered": "2025-03-19T10:56:35Z", "description": "Online no deposit", "id": 25439, "is_payment_in_progress": false, "joined": "2025-03-19T10:37:48Z", "paid": "2025-03-19T10:47:03Z", "payment_accepted": "2025-03-19T10:51:02Z", "price": 20000, "quantity": 1, "seller_id": "1-886e3c26-b585-4c92-a93b-e3c84b9b32e9", "status": "delivered", "tracked": "2025-03-19T10:51:04Z", "tracking": { "carrier": "Hermes UK", "tracking_code": "P1234567890123456" }, "tracking_details_deadline": "2025-03-23T10:51:02Z", "tracking_details_window_started": "2025-03-19T10:51:02Z" } ``` ## Step 13: Complete transaction To complete the transaction, see steps for the following. 1. [Complaints period](/docs/guides/transactions/online/online-int-path#step-8-complaints-period-optional). 2. [Payout claim](/docs/guides/transactions/online/online-int-path#step-9-seller-claims-payout).