Objects & enums

Every object and enumeration the API returns or accepts, generated from the public OpenAPI specification.

Each endpoint page shows the fields of its own request and response inline, so you rarely need this page while integrating. It exists for lookup: one stable anchor per type, for linking and for skimming the whole surface at once. → Conventions

AssetResponse BlockchainResponse CreatePaymentRequest CreateStaticWalletRequest ListPaymentsResponse ListStaticDepositsResponse ListStaticWalletsResponse PaymentResponse PublicPaymentResponse PublicRedirect QuotePaymentRequest QuotePaymentResponse RedirectConfigDTO SimulatePaymentRequest SimulateStaticDepositRequest StaticDepositResponse StaticWalletResponse TransactionList TransactionResponse UpdateStaticWalletRequest PaymentEvent StaticDepositEvent AssetID FeePayer PaymentStatusEnum PaymentSubStatusEnum ErrorResponse

Objects

AssetResponse

Field	Type	Description
`id`optional	AssetID	Asset id-string used everywhere else in the API, e.g. USDT_ARBITRUM.
`id` values AssetID `USDT_ETHEREUMUSDT_ARBITRUMUSDT_OPTIMISMUSDT_BASEUSDT_BSCUSDT_PLASMAUSDT_POLYGONUSDC_ETHEREUMUSDC_ARBITRUMUSDCE_ARBITRUMUSDC_OPTIMISMUSDC_BASEUSDC_BSCUSDC_PLASMAUSDC_POLYGONETH_ETHEREUMETH_ARBITRUMETH_OPTIMISMETH_BASEXPL_PLASMABNB_BSCPOL_POLYGONTESTCOIN_ETHEREUMTESTCOIN_OPTIMISMTESTCOIN_PLASMATESTSTABLECOIN_ETHEREUMTESTSTABLECOIN_OPTIMISMTESTSTABLECOIN_PLASMA`
`blockchainId`optional	integer	Internal blockchain ID (corresponds to GET /v1/blockchains[].id).
`contractAddress`optional	stringnull	ERC20 contract address; null for native coins (ETH, BNB, POL, XPL).
`decimals`optional	integer	Number of decimal places: smallest-unit amounts are whole tokens * 10^decimals.
`group`optional	string	Asset group, e.g. USDT, USDC, ETH.
`name`optional	string	Human-readable asset name.

BlockchainResponse

Field	Type	Description
`id`optional	integer	Internal blockchain ID.
`idString`optional	string	Network id-string, e.g. ETHEREUM, ARBITRUM (the suffix of an asset id-string).
`evmChainId`optional	integernull	EIP-155 chain ID; null for non-EVM chains.
`chainName`optional	string	Human-readable chain name.
`requiredConfirmations`optional	integer	Block confirmations required for a payment to reach finality.
`networkFeeUsd`optional	string	Flat network-fee estimate in USD (decimal string).

CreatePaymentRequest

Field Type Description

activationFlowSecondsoptional integer Grace period in seconds before the payment window starts counting, giving the customer time to open the checkout before the timer runs. Optional; range 1 to 3600 (1 hour).

amountoptional string Merchant base amount, integer string in the asset's smallest unit. When a fee payer is customer the customer is charged more than this (gross); when merchant (default) the fee is deducted from the merchant's proceeds.

assetoptional AssetID Asset the customer will pay in, as an asset id-string (e.g. USDT_ARBITRUM). Required only when the project allows more than one asset; when the project has a single asset it may be omitted. The full set of accepted values is served live at GET /v1/assets.

asset values AssetID

USDT_ETHEREUMUSDT_ARBITRUMUSDT_OPTIMISMUSDT_BASEUSDT_BSCUSDT_PLASMAUSDT_POLYGONUSDC_ETHEREUMUSDC_ARBITRUMUSDCE_ARBITRUMUSDC_OPTIMISMUSDC_BASEUSDC_BSCUSDC_PLASMAUSDC_POLYGONETH_ETHEREUMETH_ARBITRUMETH_OPTIMISMETH_BASEXPL_PLASMABNB_BSCPOL_POLYGONTESTCOIN_ETHEREUMTESTCOIN_OPTIMISMTESTCOIN_PLASMATESTSTABLECOIN_ETHEREUMTESTSTABLECOIN_OPTIMISMTESTSTABLECOIN_PLASMA

networkFeePayeroptional FeePayer Who bears the network (gas) fee. Default merchant.

networkFeePayer values FeePayer

merchantcustomer

serviceFeePayeroptional FeePayer Who bears the platform (service) fee. Default merchant.

serviceFeePayer values FeePayer

merchantcustomer

externalIdoptional string Your own identifier for this payment. Echoed back on the payment and its webhooks, and can be appended to the return URL as a redirect parameter. Optional.

metadataoptional object Arbitrary JSON key/value data to attach to the payment. Stored and echoed back unchanged on the payment and its webhooks; never sent on-chain. Use it to correlate the payment with your own records.

paymentWindowSecondsoptional integer How long the payment stays open for funding, in seconds. Optional; when omitted the project default applies. Range 300 (5 minutes) to 86400 (24 hours).

redirectConfigoptional RedirectConfigDTO Optional "return to store" redirect configuration: the base URL the customer is sent back to after paying, plus which payment identifiers to append as query parameters.

redirectConfig fields RedirectConfigDTO

Field	Type	Description
`data`optional	string	Opaque string passed through unchanged as the "data" query parameter on the return URL. Use it to carry your own session/order token.
`params`optional	string[]	Which payment identifiers to append to the return URL as query parameters. Allowed values: "id" (the Suward payment id) and "externalId" (your identifier).
`params` values string[] `idexternalId`
`url`optional	string	Base "return to store" URL the customer is sent back to after paying.

underpaymentToleranceoptional string Amount the customer may underpay and still have the payment accepted, as an integer string in the asset's smallest unit (same scale as amount). Optional; if set it must be >= 0 and strictly less than amount. Default 0 (exact amount required). Example: for amount "10000000" (10 USDT) a value of "500000" allows a 0.50 USDT shortfall.

webhookUrloptional string Webhook URL to receive this payment's events. Optional; overrides the project's default webhook URL for this payment only.

CreateStaticWalletRequest

Field	Type	Description
`allowedAssets`optional	AssetID[]	Accepted-asset allow-list, as asset id-strings (see GET /v1/assets), e.g. ["USDT_ARBITRUM"]. Deposits of assets not on this list are ignored (status "ignored") and not credited.
`allowedAssets` values AssetID `USDT_ETHEREUMUSDT_ARBITRUMUSDT_OPTIMISMUSDT_BASEUSDT_BSCUSDT_PLASMAUSDT_POLYGONUSDC_ETHEREUMUSDC_ARBITRUMUSDCE_ARBITRUMUSDC_OPTIMISMUSDC_BASEUSDC_BSCUSDC_PLASMAUSDC_POLYGONETH_ETHEREUMETH_ARBITRUMETH_OPTIMISMETH_BASEXPL_PLASMABNB_BSCPOL_POLYGONTESTCOIN_ETHEREUMTESTCOIN_OPTIMISMTESTCOIN_PLASMATESTSTABLECOIN_ETHEREUMTESTSTABLECOIN_OPTIMISMTESTSTABLECOIN_PLASMA`
`externalId`optional	string	Your own identifier for this static wallet. Echoed back on the wallet and denormalized onto each of its deposits. Optional.
`metadata`optional	object	Arbitrary JSON key/value data to attach to the static wallet. Stored and echoed back unchanged.
`webhookUrl`optional	string	Webhook URL to receive this wallet's deposit events. Optional; falls back to the project default webhook when omitted.

ListPaymentsResponse

Field Type Description

hasMoreoptional boolean True when more payments exist beyond this page. To fetch the next page, pass the last item's id as the lastId query parameter.

itemsoptional PaymentResponse[] Page of payments, ordered per the request's order parameter.

items fields PaymentResponse

Field Type Description

acceptedAtoptional integer Unix-milliseconds timestamp when the payment reached the accepted state (safe confirmations, balance credited). Null before acceptance.

activatedAtoptional integer Unix-milliseconds timestamp when the payment was activated and its payment window began counting. Null before activation.

activationFlowSecondsoptional integer Resolved activation grace period, in seconds. Null when not configured.

addressoptional string On-chain deposit address the customer must send funds to. Null until the payment is activated and an address is assigned.

amountoptional string Integer string in the asset's smallest unit.

amountConfirmedoptional string Integer string in the asset's smallest unit.

amountReceivedoptional string Integer string in the asset's smallest unit.

assetoptional AssetID Asset the payment is denominated in, as an asset id-string (see GET /v1/assets). Null until an asset is selected for the payment.

asset values AssetID

confirmedAtoptional integer Unix-milliseconds timestamp when the payment reached finalization (confirmed). Null until confirmed; may revert if a chain reorg undoes the confirmation.

createdAtoptional integer Unix-milliseconds timestamp when the payment was created.

expiresAtoptional integer Unix-milliseconds timestamp when the payment window closes; the payment expires (fails) if it has not been paid by then.

externalIdoptional string Merchant's own identifier for this payment, echoed from creation. Null when none was provided.

feeoptional string Platform fee: 0.4% of the amount, minimum $1 equivalent. Integer string in the asset's smallest unit.

idoptional string Unique Suward identifier of the payment. Use it in the payment endpoints (get, cancel, transactions) and as the checkout page path.

metadataoptional object Arbitrary key/value data attached by the merchant at creation, echoed back unchanged.

networkFeeoptional string Estimated on-chain (gas) cost, deducted from the received amount. Integer string in the asset's smallest unit.

quotedPriceoptional string USD price of the asset locked at creation, decimal string. Fees are computed from this price at settlement, so the merchant's net is deterministic.

networkFeePayeroptional FeePayer Who bears the network (gas) fee, echoed from creation.

networkFeePayer values FeePayer

merchantcustomer

serviceFeePayeroptional FeePayer Who bears the platform (service) fee, echoed from creation.

serviceFeePayer values FeePayer

merchantcustomer

paymentWindowSecondsoptional integer Resolved length of the payment window, in seconds.

projectIdoptional string Identifier of the project that owns this payment.

redirectConfigoptional RedirectConfigDTO Return-to-store redirect configuration echoed from creation. Null when none was configured.

redirectConfig fields RedirectConfigDTO

Field	Type	Description
`data`optional	string	Opaque string passed through unchanged as the "data" query parameter on the return URL. Use it to carry your own session/order token.
`params`optional	string[]	Which payment identifiers to append to the return URL as query parameters. Allowed values: "id" (the Suward payment id) and "externalId" (your identifier).
`params` values string[] `idexternalId`
`url`optional	string	Base "return to store" URL the customer is sent back to after paying.

statusoptional PaymentStatusEnum Main payment lifecycle status. See the status enum for the full meaning of each value.

status values PaymentStatusEnum

pendingacceptedsuccessfailed

subStatusoptional PaymentSubStatusEnum Fine-grained payment sub-status describing the current step or amount condition. See the sub-status enum for the full meaning of each value.

subStatus values PaymentSubStatusEnum

createdactivatedawaitingPaymentconfirmingcompletedoverpaidunderpaidexpiredcancelledpartiallyPaid

transactionsoptional TransactionList Preview page of the on-chain transactions detected for this payment (newest first). Use GET /v1/payments/{paymentId}/transactions for the full paginated list.

transactions fields TransactionList

Field	Type	Description
`hasMore`optional	boolean	True when more transactions exist beyond this page. To fetch the next page, pass the last item's id as the lastId query parameter.
`items`optional	object[]	Page of transactions, ordered per the request's order parameter.

underpaymentToleranceoptional string Integer string in the asset's smallest unit.

updatedAtoptional integer Unix-milliseconds timestamp when the payment was last updated.

webhookUrloptional string Webhook URL that receives this payment's events, echoed from creation. Null when the project default webhook is used.

paymentPageUrloptional string Absolute URL of the Suward-hosted checkout page where the customer pays this payment.

ListStaticDepositsResponse

Field Type Description

hasMoreoptional boolean True when more deposits exist beyond this page. To fetch the next page, pass the last item's id as the lastId query parameter.

itemsoptional StaticDepositResponse[] Page of static-wallet deposits, ordered per the request's order parameter.

items fields StaticDepositResponse

Field	Type	Description
`acceptedAt`optional	integer	Unix-milliseconds timestamp when the deposit reached the accepted (safe confirmations) tier. Null before acceptance.
`address`optional	string	On-chain address that received the deposit (the static wallet's address).
`amount`optional	string	Gross deposited amount, an integer string in the asset's smallest unit (see CreatePaymentRequest.amount).
`asset`optional	AssetID	Asset of the deposit, as an asset id-string (see GET /v1/assets).
`asset` values AssetID `USDT_ETHEREUMUSDT_ARBITRUMUSDT_OPTIMISMUSDT_BASEUSDT_BSCUSDT_PLASMAUSDT_POLYGONUSDC_ETHEREUMUSDC_ARBITRUMUSDCE_ARBITRUMUSDC_OPTIMISMUSDC_BASEUSDC_BSCUSDC_PLASMAUSDC_POLYGONETH_ETHEREUMETH_ARBITRUMETH_OPTIMISMETH_BASEXPL_PLASMABNB_BSCPOL_POLYGONTESTCOIN_ETHEREUMTESTCOIN_OPTIMISMTESTCOIN_PLASMATESTSTABLECOIN_ETHEREUMTESTSTABLECOIN_OPTIMISMTESTSTABLECOIN_PLASMA`
`confirmedAt`optional	integer	Unix-milliseconds timestamp when the deposit reached finality (confirmed). Null before confirmation.
`createdAt`optional	integer	Unix-milliseconds timestamp when the deposit record was created.
`detectedAt`optional	integer	Unix-milliseconds timestamp when the deposit was first detected on-chain.
`externalId`optional	string	ExternalID is the static wallet's externalId, denormalized onto the deposit.
`fee`optional	string	Platform fee on this deposit, integer string in the asset's smallest unit: max(0.4% of the amount, $1 equivalent). The $1 floor is 0 for assets without a published USD price.
`id`optional	string	Unique Suward identifier of the deposit.
`invalidatedAt`optional	integer	Unix-milliseconds timestamp when the deposit was invalidated (e.g. dropped by a chain reorg). Null unless invalidated.
`netAmount`optional	string	Amount credited to the merchant after fees (amount - fee - networkFee), integer string in the asset's smallest unit.
`networkFee`optional	string	Estimated on-chain (gas) cost deducted from the deposit, integer string in the asset's smallest unit.
`projectId`optional	string	Identifier of the project that owns this deposit.
`staticWalletId`optional	string	Identifier of the static wallet that received this deposit.
`status`optional	string	Deposit lifecycle status. detected: seen on-chain, awaiting confirmations. accepted: safe confirmations reached, credited (non-final). confirmed: finalized (terminal). ignored: the asset is not on the wallet's allow-list, so the deposit is not credited. invalidated: dropped after detection, e.g. by a chain reorg.
`status` values string `detectedacceptedconfirmedignoredinvalidated`
`transferIndex`optional	string	Index of this transfer within its transaction, as a string-encoded integer. Distinguishes multiple transfers to the same address in one transaction.
`txHash`optional	string	On-chain transaction hash of the deposit.
`updatedAt`optional	integer	Unix-milliseconds timestamp when the deposit was last updated.

ListStaticWalletsResponse

Field Type Description

hasMoreoptional boolean True when more static wallets exist beyond this page. To fetch the next page, pass the last item's id as the lastId query parameter.

itemsoptional StaticWalletResponse[] Page of static wallets, ordered per the request's order parameter.

items fields StaticWalletResponse

Field	Type	Description
`address`optional	string	Reusable on-chain deposit address of this static wallet. Customers may send accepted assets to it repeatedly; each incoming transfer becomes a deposit.
`allowedAssets`optional	AssetID[]	Accepted-asset allow-list, as asset id-strings (see GET /v1/assets). Deposits of assets outside this list are ignored and not credited.
`allowedAssets` values AssetID `USDT_ETHEREUMUSDT_ARBITRUMUSDT_OPTIMISMUSDT_BASEUSDT_BSCUSDT_PLASMAUSDT_POLYGONUSDC_ETHEREUMUSDC_ARBITRUMUSDCE_ARBITRUMUSDC_OPTIMISMUSDC_BASEUSDC_BSCUSDC_PLASMAUSDC_POLYGONETH_ETHEREUMETH_ARBITRUMETH_OPTIMISMETH_BASEXPL_PLASMABNB_BSCPOL_POLYGONTESTCOIN_ETHEREUMTESTCOIN_OPTIMISMTESTCOIN_PLASMATESTSTABLECOIN_ETHEREUMTESTSTABLECOIN_OPTIMISMTESTSTABLECOIN_PLASMA`
`createdAt`optional	integer	Unix-milliseconds timestamp when the static wallet was created.
`externalId`optional	string	Your own identifier for this static wallet, echoed from creation. Null when none was provided.
`id`optional	string	Unique Suward identifier of the static wallet.
`metadata`optional	object	Arbitrary key/value data attached by the merchant, echoed back unchanged.
`projectId`optional	string	Identifier of the project that owns this static wallet.
`updatedAt`optional	integer	Unix-milliseconds timestamp when the static wallet was last updated.
`webhookUrl`optional	string	Webhook URL that receives this wallet's deposit events. Null when the project default webhook is used.

PaymentResponse