Compatibility and known limitations

You can skip this page for a standard integration. Refer to it when comparing production with preview environments or when implementing Custom Payment Flow.

Verification baseline

Component	Version
TRADOM Payment backend	`production@f267bf0`
TypeScript SDK source	`@tradom/payment@0.5.0`
npm latest	`@tradom/payment@0.5.0`
Last verified	2026-08-17

Production REST API alignment

Capability	Production REST API	SDK 0.5.0
Gateway order `mode`	`live` / `testnet` / `simulate` (staging coerces `live` → `testnet`)	Supported by `createOrder({ mode })`; read the effective mode from `OrderApproved.mode`
Gateway order `currency`	`JPY` (default) / `USD`	`createOrder({ amount, currency })` plus typed response/status/quote `amount` and `currency`
Gateway status deposit receipt	`underpaid` / `sent_amount` / `expected_amount` / `tx_hash` / `paid_amount` / `paid_currency` / `paid_network`	Same fields in camelCase on `CheckoutStatus`
Gateway status `mode` / `faucets`	Included in the response	Mapped to `CheckoutStatus`
Gateway checkout controls	Asset selection, quote refresh, ToS, simulation, reference quote, wallet check (verify-status / extend-session / reset-verification), slippage verdict	Exposed as dedicated methods
TRON / USDT	When Tron payments are enabled for the merchant	Supports `network: "tron"` and asset quotes
`bridging` state	Thirteenth canonical state	Explicitly included in `OrderStateName`
`client_secret` operations	Accepted through `X-Client-Secret` or the request body	Supported by options on `retrieve`, `cryptoQuote`, and `confirm`

Every endpoint the SDK calls is deployed in production. There are no known SDK field gaps against the production REST API.

Differences on staging (preview)

Staging runs on a Fireblocks sandbox workspace, so orders created without a mode or with mode: "live" are created as testnet (simulate is left as is). Read mode from the response / checkoutStatus.
Calling an endpoint that has not been deployed returns 404.

Custom Payment Flow

The current production release has these limitations:

Onchain PaymentIntent deposits are not connected to automatic state updates
There is no submit_tx endpoint
Only simulate completes end to end
simulateDeposit(id, { amount }) advances to succeeded without distinguishing underpayment or overpayment, and only works on a simulate-mode intent created with sk_test_…
mode is not enumeration-checked by the REST API (a value other than the three creates the intent, and the later simulate_deposit fails)
Idempotency-Key is scoped to the merchant as a whole (reusing a key across sk_test and sk_live returns the existing intent)

Use Hosted Checkout for live and testnet onchain payments.

Webhooks

The current production release delivers three event types:

payment_intent.succeeded
payment_intent.canceled
payment_intent.refunded

It does not deliver payment_intent.created or refund.created. Gateway orders (Hosted Checkout) do not emit webhooks; reconcile with checkoutStatus.

Delivery is attempted at most 5 times in total (initial + 4 retries, within 72 hours), with a 5-second timeout per attempt; only a 2xx counts as success and redirects are not followed.