---
updatedAt: 2026-09-14T20:30:29.000Z
agentTools:
  projectIndex: https://docs.withreach.com/llms.txt
---

# Transaction details

Send tax data to complete your transaction records

When line-item tax details are not sent directly from a tax provider, the supplier or partner must provide this information via the <Anchor target="_blank" href="https://docs.withreach.com/reference/submittransactiondetails">Transaction Details API</Anchor> to maintain comprehensive transaction and tax records for compliance and reporting.

# Using the Transaction Details API

Suppliers can use the `/transaction-details` endpoint to submit tax details that are not passed on to Reach by a tax provider.

The inclusion or exclusion of the `PspName` and `PspTransactionId` fields determine how Reach handles your tax details:

* **Tax linking**: include the `PspName` and `PspTransactionId` to provide tax details for a corresponding payment record. Use when a tax provider only passes tax data to the supplier or billing partner, but not to Reach.
* **Tax only**: omit the `PspName` and `PspTransactionId` fields to provide tax details when Reach does not process a supplier's payments, but does provide services for tax filing.

<HeadingWithPill title="Tax linking flow" label="Include PSP fields" level={2} bg="#1E1A15" color="#FAF7F5"/>

When the customer makes a purchase, the supplier or billing platform calls their tax provider to calculate tax. Upon the customer completing the checkout process, the supplier or billing platform passes the transaction to the PSP for processing.

![](https://files.readme.io/bb6a559a5111db2a9b70f4a4975c4e7633478d0fc31f1cf1ea26924705058780-Reach_-_Transaction_Details_API_Tax_Linking_Workflow.png)

A PSP processes the transaction and provides Reach with the correlated payment details via a webhook. The supplier or billing platform sends the tax portion of the transaction to Reach using the `/transaction-details` endpoint.

Reach matches the records, and the complete record is used for tax filing, remittance, and settlement reports.

<HeadingWithPill title="Tax only flow" label="Omit PSP fields" level={2} bg="#1E1A15" color="#FAF7F5"/>

A fulfillment partner or logistics provider calculates tax via their own provider. They send the returned tax amounts, rates, and related information to Reach using the Transaction Details API for reporting and compliance.

Reach records this submission using its `Reference` value, as there is no PSP payment to match it against.

<Image src="https://files.readme.io/b5f83360aae2c4a8cf12a8e75a7bbd002469e719c9e09d4cfc1309ddaaac966f-Reach_-_Transaction_Details_API_Tax_Only_Workflow.png" width="100%" />

## Transaction Details API request

On a successful request, the API returns a `202 Accepted` response with no body. Validation errors return actionable messages.

### Rate limiting

Reach recommends staying under 10 requests per second per integrator account. Requests over the limit receive an HTTP `429 Too Many Requests` response. If you receive a `429 Too Many Requests` response, back off and retry with an exponential delay.

<CardCallout type="warning" title="High volume">
 The Reach cloud gateway may throttle or reject sustained traffic above the limit. If you anticipate higher volume, contact the Reach team during onboarding to adjust your limits.
</CardCallout>

### Credentials

The Transaction Details API uses HTTP Basic Auth (username and password issued by Reach during onboarding) and requires a `Reach-Merchant-Id` header set to the merchant UUID Reach assigns. Requests missing either credential are rejected with a `401 Unauthorized` response before the body is processed.

### Idempotency guidelines

After the first request is accepted, any duplicate submissions are ignored. Duplicate submissions return a `202 Accepted`  response.

For tax linking, the `PspTransactionId` value is the idempotency key, while for tax only, the `Reference` value is used as the idempotency key.

### Payment examples

For tax linking payments, Reach can receive the Transaction Details API request or the PSP's webhook in any order; whichever is received first will be held until the correlated data is received.

Suppliers using tax linking must include PSP-related fields to link tax data to a corresponding payment, while those using tax only should omit both the `PspTransactionId` and the `PspName` fields.

```json Tax linking payment request
curl --request POST \
     --url https://api.withreach.com/v2/transaction-details \
     --header 'accept: application/json' \
		 --header 'authorization: Basic =============' \
     --header 'content-type: application/json' \
     --data '
{
  "PspTransactionId": "5TYX2345XB678X01C",
  "PspName": "PAYPAL",
  "Reference": "10965",
  "Currency": "USD",
  "ShippingAddress": {
    "Street": "123 Main St",
    "City": "Los Angeles",
    "Region": "CA",
    "Country": "US",
    "Postcode": "90001"
  },
  "TaxProviderId": "tx-8a7f808a",
  "TaxProviderReferenceId": "EXG-INV-10965",
  "TaxDate": "2026-03-10T15:30:00",
  "Items": [
    {
      "Sku": "PREMIUM-MONTHLY",
      "Description": "Premium Streaming Bundle - Monthly",
      "Quantity": 1,
      "Amount": 20,
      "ProviderTaxCode": "SW096789",
      "ProviderTaxCategory": "DIGITAL_STREAMING",
      "ProviderParentTaxCategory": "DIGITAL_GOODS",
      "TaxAmount": 1.25,
      "ItemTaxes": [
        {
          "Name": "CA State Sales Tax",
          "Type": "SALES",
          "JurisdictionName": "California",
          "JurisdictionLevel": "STATE",
          "JurisdictionCountryCode": "US",
          "JurisdictionRegionCode": "CA",
          "TaxableAmount": 20,
          "NonTaxableAmount": 0,
          "TaxRate": 0.0625,
          "TaxAmount": 1.25,
          "TransactionType": 19,
          "ServiceType": 6
        }
      ]
    }
  ]
}
'
```
```json Tax only payment request
curl --request POST \
     --url https://api.withreach.com/v2/transaction-details \
		 --header 'accept: application/json' \
		 --header 'authorization: Basic =============' \
     --header 'content-type: application/json' \
     --data '
{
  "Reference": "10965",
  "Currency": "AUD",
  "WarehouseAddress": {
    "Street": "200 N Spring St",
    "City": "Los Angeles",
    "Region": "CA",
    "Country": "US",
    "Postcode": "90012"
  },
  "ShippingAddress": {
    "Street": "100 George Street",
    "City": "Sydney",
    "Region": "NSW",
    "Country": "AU",
    "Postcode": "2000"
  },
  "TaxProviderId": "tax-txn-8a7f808a",
  "TaxProviderReferenceId": "INV-10965",
  "TaxDate": "2026-03-10T15:30:00",
  "Items": [
    {
      "Sku": "SHIRT_4353_W12",
      "Description": "Premium White Cotton T-Shirt - Size 12",
      "CountryOfOrigin": "US",
      "Quantity": 1,
      "Amount": 20,
      "ProviderTaxCode": "PC040100",
      "TaxAmount": 2,
      "ItemTaxes": [
        {
          "Name": "Australia GST",
          "Type": "SALES",
          "JurisdictionName": "Australia",
          "JurisdictionLevel": "FEDERAL",
          "JurisdictionCountryCode": "AU",
          "TaxableAmount": 20,
          "NonTaxableAmount": 0,
          "TaxRate": 0.1,
          "TaxAmount": 2
        }
      ]
    }
  ]
}
'
```
```json Tax linking response
Accepted
```
```json Tax only response
Accepted
```

## Refunds with the Transaction Details API

A reversal is indicated by the presence of the parent identifier.

For refunds, all `Amount`, `TaxAmount`, `TaxableAmount`, and `NonTaxableAmount` values in the `Items` object must be negative (with the exception of zero values).

**For suppliers using tax linking,** use the `ParentPspTransactionId` to issue a refund. The `ParentPspTransactionId` is the original `PspTransactionId` of the payment being reversed.&#x20;

**For suppliers using tax only,** use the `ParentReference` to issue a refund. The `ParentReference` is the original `Reference` ID of the payment being reversed.

```json Tax linking refund example
curl --request POST \
     --url https://api.withreach.com/v2/transaction-details \
     --header 'accept: application/json' \
     --header 'authorization: Basic ===============' \
     --header 'content-type: application/json' \
     --data '
{
  "PspTransactionId": "9GH11222IJ334455K",
  "ParentPspTransactionId": "5TY12745A6678901C",
  "PspName": "PAYPAL",
  "Reference": "10967",
  "Currency": "USD",
  "ShippingAddress": {
    "Street": "123 Main St",
    "City": "Los Angeles",
    "Region": "CA",
    "Country": "US",
    "Postcode": "90001"
  },
  "TaxProviderId": "tax-txn-9c2e114b",
  "TaxProviderReferenceId": "ID-CRN-10967",
  "TaxDate": "2026-03-11T09:00:00",
  "Items": [
    {
      "Sku": "PREMIUM-MONTHLY",
      "Description": "Premium Streaming Bundle - Monthly (Refund)",
      "Quantity": 1,
      "Amount": -20,
      "ProviderTaxCode": "SW056789",
      "ProviderTaxCategory": "DIGITAL_STREAMING",
      "ProviderParentTaxCategory": "DIGITAL_GOODS",
      "TaxAmount": -1.25,
      "ItemTaxes": [
        {
          "Name": "CA State Sales Tax",
          "Type": "SALES",
          "JurisdictionName": "California",
          "JurisdictionLevel": "STATE",
          "JurisdictionCountryCode": "US",
          "JurisdictionRegionCode": "CA",
          "TaxableAmount": -20,
          "NonTaxableAmount": 0,
          "TaxRate": 0.0625,
          "TaxAmount": -1.25,
          "TransactionType": 19,
          "ServiceType": 6
        }
      ]
    }
  ]
}
'
```
```json Tax only refund example
curl --request POST \
     --url https://api.withreach.com/v2/transaction-details \
     --header 'accept: application/json' \
		 --header 'authorization: Basic ================' \
     --header 'content-type: application/json' \
     --data '
{
  "Reference": "10907",
  "ParentReference": "90965",
  "Currency": "AUD",
  "WarehouseAddress": {
    "Street": "200 N Spring St",
    "City": "Los Angeles",
    "Region": "CA",
    "Country": "US",
    "Postcode": "90012"
  },
  "ShippingAddress": {
    "Street": "100 George Street",
    "City": "Sydney",
    "Region": "NSW",
    "Country": "AU",
    "Postcode": "2000"
  },
  "TaxProviderId": "tax-txn-9c2e114b",
  "TaxProviderReferenceId": "CRN-10967",
  "TaxDate": "2026-03-11T09:00:00",
  "Items": [
    {
      "Sku": "SHIRT_4353_W12",
      "Description": "Premium White Cotton T-Shirt - Size 12 (Refund)",
      "CountryOfOrigin": "US",
      "Quantity": 1,
      "Amount": -20,
      "ProviderTaxCode": "PC040100",
      "TaxAmount": -2,
      "ItemTaxes": [
        {
          "Name": "Australia GST",
          "Type": "SALES",
          "JurisdictionName": "Australia",
          "JurisdictionLevel": "FEDERAL",
          "JurisdictionCountryCode": "AU",
          "TaxableAmount": -20,
          "NonTaxableAmount": 0,
          "TaxRate": 0.1,
          "TaxAmount": -2
        }
      ]
    }
  ]
}
'
```

## The `PspTransactionId` field

PSPs return multiple ID fields in their responses, and using the wrong one causes silent matching failures.

<CardCallout type="warning" title="Tax linking">
  The `PspTransactionId` field is only required when completing tax linking with the Transaction Details API. This section can be disregarded for tax only.
</CardCallout>

### Payments

The `PspTransactionId` field accepts the following values for tax linking payment calls:

<DataTable
  caption="`PspTransactionId` mapping for **payments**"
  headers="PSP|Accepted values|Notes"
  columnTypes="code|code|text"
>
  <DataTableRow data="Adyen|pspReference|From the `/payments` response." />
  <DataTableRow data="Checkout.com|id|From `/payments` response (e.g., pay_cawsap...)." />
  <DataTableRow data="PayPal|purchase_units[].payments.captures[].id|From order capture, use the capture ID, not the top-level order ID." />
  <DataTableRow data="Stripe|charges.data.id|From `/payment_intents` response." />
</DataTable>

### Refunds

The `PspTransactionId` field accepts the following values for tax linking refund calls:

<DataTable
  caption="`PspTransactionId` mapping for **refunds**"
  headers="PSP|Accepted values|Notes"
  columnTypes="code|code|text"
>
  <DataTableRow data="Adyen|`pspReference`|From `/refunds` response. Not `paymentPspReference`. The refund `pspReference` is the new refund ID; the original payment's `pspReference` goes in the `ParentPspTransactionId` field." />
  <DataTableRow data="Checkout.com|`action_id`|From `/payments/{id}/refunds` response (e.g. `act_m7ltl...`)." />
  <DataTableRow data="PayPal|`id`|From `/payments/captures/{id}/refund`." />
  <DataTableRow data="Stripe|`id`|From `/refunds` response." />
</DataTable>

Set the `ParentPspTransactionId` field to the original `PspTransactionId` for the payment being reversed.

## Postman collection

A Postman collection is available to help you test and explore the API. Download the JSON file and import it into Postman to get started.

<ReachDataCard title="Download the Postman collection" link="https://drive.google.com/file/d/1sFTgBMg8cAb8wbMKh8FWK4rvUcz5xCNz/view?usp=sharing" />

<div
  style={{
    marginLeft: '5px',
    marginRight: '5px', 
    color: '#FAF7F5',    
    paddingLeft: '20px',
    paddingRight: '20px',
    paddingTop: '20px',
    paddingBottom: '10px',
    backgroundColor: '#1E1A15',
    maxWidth: '1000%',
    borderRadius: '10px'
      }}
  >
  For additional assistance or inquiries <p style={{color:'#999177'}}>contact your Reach representative or our support team at [support@withreach.com](mailto:support@withreach.com).</p>
</div>