Submit transaction details

post

https://api.withreach.com/v2/transaction-details

The Transaction Details API enables suppliers and partners to submit line-item tax data to Reach, including jurisdiction, rates, codes, and amounts. It services two functions:

Tax linking: for suppliers using Reach as Merchant of Record—correlates tax details to a PSP transaction via PspTransactionId and PspName.
Tax only: for fulfillment partners not processing payments through Reach—accepts tax records for filing purposes using a Reference ID.

Refunds and reversals are submitted with a parent identifier linking back to the original record, with all monetary amounts negative. Duplicate submissions are silently ignored—only the first request is processed. All requests require HTTP Basic Auth and a Reach-Merchant-Id header. Submissions should not exceed 10 requests per second.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Transaction details to submit.

Suppliers or billing platforms provide tax details to Reach. Reach correlates this submission to the PSP webhook using PspTransactionId. Both PspTransactionId and PspName are required. The submission and the webhook may arrive in either order—both are persisted and correlated once both have arrived. For refunds, set ParentPspTransactionId to the original payment's PspTransactionId and use negative amounts throughout.

PspTransactionId

string

required

Transaction ID from the PSP. This is the correlation key Reach uses to match this submission to the PSP webhook. Omitted in Tax only. See the PSP Transaction ID mapping table for the exact field to use for each PSP.

PayPal payments: purchase_units[].payments.captures[].id (the capture ID, not the order ID).
PayPal refunds: id from the refund response.
Adyen payments: pspReference from the payment response.
Adyen refunds: pspReference from the refund response (not paymentPspReference).
Checkout.com payments: id from /payments response.
Checkout.com refunds: id from /payments/{payment_id}/refunds response.
Stripe payments: charges.data.id from /payment_intents response.
Stripe refunds: id from /refunds response.

PspName

string

enum

required

PSP that processed the payment. Omitted in Tax only

Allowed:

ParentPspTransactionId

string

The PspTransactionId of the original payment being reversed. Set this field to indicate a refund or reversal—no separate boolean is needed. When present, all Amount, TaxAmount, TaxableAmount, and NonTaxableAmount values in Items must be negative.

PayPal: use the original capture ID.
Adyen: use the original payment pspReference.
Checkout.com refunds: id from /payments/{payment_id}/refunds response.
Stripe refunds: id from /refunds response.

Reference

string

required

Your order ID or internal reference for this transaction.

Currency

string

required

^[A-Z]{3}$

ISO 4217 three-letter currency code.

ShippingAddress

object

required

A postal address used for tax jurisdiction determination.

WarehouseAddress

object

A postal address used for tax jurisdiction determination.

TaxProviderId

string

required

Transaction ID returned by your tax provider for this calculation.

TaxProviderReferenceId

string

required

The reference your system passed into the tax provider when requesting the tax calculation.

BusinessIdentificationNumber

string

Tax ID or VAT registration number. Provides evidence for why tax may be zero on B2B transactions.

TaxDate

string

required

^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

Local date and time of the tax calculation. Format: yyyy-MM-ddTHH:mm:ss—no timezone offset, no fractional seconds.

Items

array of objects

required

length ≥ 1

Line items on the transaction. Must contain at least one item.

Items*

Headers

Reach-Merchant-Id

uuid

required

^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

The merchant UUID issued by Reach during onboarding. Requests missing or carrying an unrecognized value are rejected with 401 Unauthorized before the body is processed.

Responses

202

Accepted response with no body. The transaction details have been received and persisted. A duplicate submission with the same PspTransactionId in tax linking, and Reference in Tax only also returns a 202 Accepted response — only the first submission is processed.

429

Too Many Requests—the rate limit has been exceeded. Back off and retry with exponential delay. We recommend keeping submissions under 10 requests per second per integrator account. Contact Reach during onboarding to request a higher limit if sustained higher throughput is required.

400Bad Request — the request body failed validation. Returns a structured error with field-level detail.

401Unauthorized — Basic Auth credentials are missing or invalid, or the Reach-Merchant-Id header is missing or not recognized.