# 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-cc). ### Create a sellers and buyers Follow our [users](/docs/guides/transactions/users) guide to create user IDs for both seller and buyer. ### 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€. 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 } ``` ### 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": "Blue t-shirt with owl decal", "price": 20000, "charge": 720, "charge_calculator_version": 5, "payment_method": "card", "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": "Blue t-shirt with owl decal", "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" } ``` ### 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). While not required, some shipping carriers may need an `email` addresses for both your seller and buyer. Add these when adding addresses. 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", "email":"sarah.garcia@shopit.com", "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", "email":"sarah.garcia@shopit.com" } ``` ### 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", "email":"bert.gray@my-mail.com", "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", "email":"bert.gray@my-mail.com" } ``` ### 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" } ``` ### 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": "Blue t-shirt with owl decal", "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" } ``` ### 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" } ] ``` ### 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 ### 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. | Use case | URL | | --- | --- | | 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/25439/guest_pay?redirect_uri=https://www.example.com ``` The payment screen looks like the following. Image with dimensions Bank transfer Ensure, you have following configured. * [Calculate charge](#step-1-create-buyers-sellers-and-calculate-charges) to include `payment_method=bank_transfer`. * [Transaction creation](#step-2-create-a-transaction) to include `"payment_method": "bank_transfer"`. Guide your buyer to pay using the [Trustap payment screen](#step-9-buyer-transfers-funds). Instead of card payment details, your buyer will be shown bank transfer details after they submit their personal details. Alternatively, you can use the [bank details endpoint](/apis/openapi/online-payment/basic.getbanktransferdetails). ```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" } ``` 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. ### 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": "Blue t-shirt with owl decal", "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" } ``` ### 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" } ``` ### 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": "Blue t-shirt with owl decal", "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" } ``` ### Complaints period 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). ### Seller claims transaction 1. A seller must register for a full Trustap account before they can claim a transaction. See our [full user guide](/docs/guides/transactions/full-users) for details. 2. Using the seller full Trustap account user ID as `Trustap-User`, claim the transaction. This links the transaction to their full Trustap account. ```CURL Seller claims transaction 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 ':' ``` 1. Following confirmation of delivery and a successful complaints period, the seller will receive the payout from the transaction to their account.