API objects
Fields on PaymentIntent, CryptoQuote, Refund, Event, and WebhookEndpoint objects
The SDK converts REST API snake_case fields to TypeScript-friendly camelCase.
| Object | Example ID | Purpose |
|---|---|---|
| PaymentIntent | pi_… | Amount, status, deposit instructions, refunds, and internal transactions for one payment |
| CryptoQuote | cq_… | Preview of the stablecoin quantity and reference rate |
| Refund | RF-… | Refund ledger entry attached to a PaymentIntent |
| Event | evt_… | PaymentIntent completion, cancellation, or refund event |
| WebhookEndpoint | Numeric ID | Merchant endpoint that receives webhooks |
PaymentIntent
| SDK field | Description |
|---|---|
amount | Charge amount in the fiat currency's major unit |
amountReceived | Recorded amount received |
amountRefunded | Amount requested for refund |
currency | Lowercase fiat currency code, such as jpy or usd |
status | requires_payment_method / requires_action / processing / succeeded / canceled / failed |
clientSecret | Browser authorization for a hosted session; omitted from webhook snapshots |
nextAction | Deposit instructions while in requires_action; otherwise null |
transactions | Transaction hashes (explorerUrl is always null in the current implementation) |
refunds.data | Refunds attached to this payment |
metadata | Arbitrary merchant data |
livemode | Whether the object was created with a live key |
settlement | Internal transfer ID, channel, and transaction hash; not a settlement-complete status |
amount uses a fiat currency's major unit. Token quantities such as nextAction.cryptoDeposit.amount are strings to preserve decimal precision.
Deposit instructions
Key fields in nextAction.cryptoDeposit:
| Field | Description |
|---|---|
stablecoin / network | Selected payment rail |
chainId / tokenContract | Chain information required by the wallet |
depositAddress | Destination address |
amount | Token quantity to send, represented as a string |
eip681Uri | URI for QR codes and wallet deep links |
expiresAt | Deposit deadline as Unix seconds |
refreshRemaining | Informational only (always 2 in the current implementation; re-confirm is not limited) |
mode | simulate / testnet / live |
faucets | Testnet faucet links |
CryptoQuote
A cryptoQuote is a read-only preview. It is valid for about 15 minutes, but confirm does not lock the cq_… quote and recalculates the token amount. Display nextAction.cryptoDeposit.amount from the confirmation response as the final transfer amount.
Refund
refunds.data on a PaymentIntent contains its refund ledger entries. status: "requested" means a refund has been requested, not that funds have already been returned.
Event
| SDK field | Meaning |
|---|---|
id | evt_…; the same value as the Tradom-Event-Id webhook header |
object | Always "event" |
type | payment_intent.succeeded / payment_intent.canceled / payment_intent.refunded |
created | Time of occurrence (Unix seconds); may be null |
data.object | PaymentIntent snapshot at the time of the event |
livemode | Whether the event originated from a live key |
data.object contains a PaymentIntent snapshot from the time the event occurred. It excludes clientSecret. See Receive payment events for supported event types.
WebhookEndpoint
| SDK field | Meaning |
|---|---|
id | Numeric ID |
url | Delivery URL (https / http only; private and loopback addresses are rejected with url_invalid) |
enabled | Whether the endpoint is active (there is currently no API to change it) |
secret | whsec_…; returned only in the create response, never by list |