Transaction items

A transaction is the primary object in Trustap, representing an agreement between a buyer and seller to pay for goods or services. While a transaction can cover a single lump sum, adding transaction items enables you to break down the total cost into distinct elements.

Itemizing a transaction is helpful for the following.

Order Management: Tracking distinct physical or digital items within a combined order.
Inventory & Stock Tracking: Keeping line-item records for stock allocation.
Tax & Reporting: Allocating precise tax amounts (amount_tax) and extra charges per item for accounting purposes.

Transaction items can be added to a transaction before or after a transaction has been paid for.

Workflow overview

Adding items to a transaction follows a three-step sequence.

Create the transaction

Calculate applicable fees and create the core transaction object representing the total order value.

Attach items

Send a POST request to the transaction's /items endpoint with line-item details.

Process payment

Redirect the buyer to the generated payment_link to complete payment.

Important breakdown rules

When attaching items to a transaction, the sum of all individual item fields must strictly match the parent transaction values.

Base Amount + Tax: The sum of item.amount + item.amount_tax across all items must equal transaction.amount.
Extra Charges: The sum of item.amount_extra across all items must equal transaction.amount_extra.
Postage/Shipping: The sum of item.amount_postage across all items must equal transaction.amount_postage.

Add items to a transaction

Step 1: Calculate fees and create transaction

Query the fee endpoint for your currency and payment method, then create the base transaction.

1. Calculate fees

curl -i -X GET \
  -u '<API_KEY>:' \
  'https://api.test.trustap.com/v2/fees?currency=eur&amount=20000&amount_extra=100&amount_postage=0&payment_method=card'

2. Create transaction

curl -i -X POST \
  https://api.test.trustap.com/v2/transactions \
  -u '<API_KEY>:' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 20000,
    "amount_extra": 100,
    "amount_postage": 0,
    "currency": "eur",
    "description": "Trustap socks",
    "fees_buyer": 1055,
    "payment_method": "card",
    "role": "buyer",
    "seller_id": "1-a91647f1-0cda-4d6c-b95f-b08de714dcd9",
    "buyer_id": "1-a5034d6a-1110-4d33-b6dd-c6ff1b3b2e28"
  }'

Step 2: Add items to transaction

Before payment, post the breakdown array to the transaction's items endpoint. Ensure the values for amount, amount_tax, amount_extra, and amount_postage follow the breakdown rules.

Base + Tax Total: €(4800 + 200) + (10000 + 0) + (4800 + 200) = 20000 (Matches transaction amount)

Extra Total: €50 + 40 + 10 = 100€ (Matches transaction amount_extra)

Use billing_type to set the billing occurrence. Use "billing_type": "one_time" for one time payment and "billing_type": "recurring" for subscription billing.

curl -i -X POST \
  'https://api.test.trustap.com/v2/transactions/tx_01m3m96hmmed4rhyph7q555w1n/items' \
  -u '<API_KEY>:' \
  -H 'Content-Type: application/json' \
  -H 'Trustap-User: 1-a91647f1-0cda-4d6c-b95f-b08de714dcd9' \
  -d '{
    "items": [
      {
        "description": "red sock",
        "quantity": 1,
        "amount": 4800,
        "amount_tax": 200,
        "amount_extra": 50,
        "amount_postage": 0,
        "billing_type": "one_time"
      },
      {
        "description": "blue sock",
        "quantity": 1,
        "amount": 10000,
        "amount_tax": 0,
        "amount_extra": 40,
        "amount_postage": 0,
        "billing_type": "one_time"
      },
      {
        "description": "green sock",
        "quantity": 1,
        "amount": 4800,
        "amount_tax": 200,
        "amount_extra": 10,
        "amount_postage": 0,
        "billing_type": "one_time"
      }
    ]
  }'

When the items endpoint returns, the transaction object includes an items array with assigned item IDs (item_id) and timestamps.

{
  "id": "tx_01m3m96hmmed4rhyph7q555w1n",
  "status": "paid",
  "description": "Trustap socks",
  "items": [
    {
      "item_id": "it_01m3m9pf9yed4ta6yb8dwdq89t",
      "description": "red sock",
      "quantity": 1,
      "amount": 4800,
      "amount_tax": 200,
      "amount_extra": 50,
      "amount_postage": 0,
      "billing_type": "one_time",
      "created": "2026-09-28T15:21:23.030670445Z"
    },
    {
      "item_id": "it_01m3m9pfa4ed4r12mpvzz9zt3f",
      "description": "blue sock",
      "quantity": 1,
      "amount": 10000,
      "amount_tax": 0,
      "amount_extra": 40,
      "amount_postage": 0,
      "billing_type": "one_time",
      "created": "2026-09-28T15:21:23.030670445Z"
    },
    {
      "item_id": "it_01m3m9pfa9ed4stzk0mck71na8",
      "description": "green sock",
      "quantity": 1,
      "amount": 4800,
      "amount_tax": 200,
      "amount_extra": 10,
      "amount_postage": 0,
      "billing_type": "one_time",
      "created": "2026-09-28T15:21:23.030670445Z"
    }
  ],
  "pricing": {
    "amount": 20000,
    "amount_extra": 100,
    "amount_postage": 0,
    "currency": "eur",
    "fees": {
      "buyer": 1055,
      "buyer_client": 0,
      "international_payment": 316,
      "seller": 0,
      "seller_client": 0
    },
    "postage_bearer": "buyer"
  }
}

Step 3: Complete payment

Redirect the buyer to the payment_link returned in the creation payload:

https://actions.stage.trustap.com/transactions/tx_01m3m96hmmed4rhyph7q555w1n/pay?redirect_uri=<YOUR-REDIRECT-URI>

Once the user completes checkout, the transaction state updates to "status": "paid".