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 Transaction Details API 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
PspNameandPspTransactionIdto 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
PspNameandPspTransactionIdfields to provide tax details when Reach does not process a supplier's payments, but does provide services for tax filing.
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.
A PSP processes the transaction, and the correlated payment details are provided to Reach via a webhook. The supplier or billing platform sends the tax portion of the transaction to Reach using the Transaction Details API.
Reach matches the records, and the complete record is used for tax filing, remittance, and settlement reports.
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.
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.
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.
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.
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",
"TaxIncluded": false,
"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
}
]
}
]
}
'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",
"TaxIncluded": false,
"TaxAmount": 2,
"ItemTaxes": [
{
"Name": "Australia GST",
"Type": "SALES",
"JurisdictionName": "Australia",
"JurisdictionLevel": "FEDERAL",
"JurisdictionCountryCode": "AU",
"TaxableAmount": 20,
"NonTaxableAmount": 0,
"TaxRate": 0.1,
"TaxAmount": 2
}
]
}
]
}
'AcceptedAcceptedRefunds 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.
For suppliers using tax only, use the ParentReference to issue a refund. The ParentReference is the original Reference ID of the payment being reversed.
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",
"TaxIncluded": false,
"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
}
]
}
]
}
'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",
"TaxIncluded": false,
"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
PspTransactionId fieldPSPs return multiple ID fields in their responses, and using the wrong one causes silent matching failures.
The PspTransactionId field is only required when completing tax linking with the Transaction Details API. This section can be disregarded for tax only.
Payments
The PspTransactionId field accepts the following values for tax linking payment calls:
Refunds
The PspTransactionId field accepts the following values for tax linking refund calls:
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.
contact your Reach representative or our support team at [email protected].