Payments
Create and track crypto payment requests. Each payment gets a unique deposit address.
A payment is a one-time request to collect a fixed amount of a single asset at a unique, single-use deposit address. Create the payment, hand the customer its address, then follow it to finality with webhooks or polling.
Lifecycle: Pending → Accepted (safe confirmations reached — safe to release goods) → Success (finalized and credited to your project balance), or Failed (expired, cancelled, or reorg-invalidated).
Fees. The platform fee is max(0.4%, $1 equivalent); an estimated network (gas) fee is added on top. Preview both with POST /v1/payments/quote before creating a payment.
Settings you control at creation. The asset (asset, required — the customer never picks it); who pays each fee (serviceFeePayer / networkFeePayer: merchant deducts from your proceeds, customer adds to what they pay); underpaymentTolerance; the payment window (paymentWindowSeconds); an optional two-step activation flow (activationFlowSeconds); a per-payment webhookUrl and redirectConfig; and arbitrary metadata (≤4 KiB). The asset's USD price is locked at creation (quotedPrice) so your net stays deterministic.
Conventions shared by every endpoint — auth, amounts, timestamps, pagination — are on the reference overview. The full walkthrough lives in the Payments guide.
Endpoints
/v1/paymentsReturn a paginated list of the project's payments, newest first. Page and sort the results with the order, limit, and lastId query parameters.POSTCreate payment/v1/paymentsCreate a payment request. Returns a unique, single-use deposit address and the amount to collect; the customer pays and you track progress via webhooks or polling. Pass externalId to make the call idempotent and dedupe retries.GETGet payment/v1/payments/{paymentId}Returns full payment details when called with an API key (merchant view).
Returns limited payment details when called without an API key (customer view).POSTActivate payment/v1/payments/{paymentId}/activateActivate a payment (public, customer-facing)POSTCancel payment/v1/payments/{paymentId}/cancelCancel a payment that has not yet completed. It stops accepting funds and moves to a terminal Failed state. Only valid from early statuses (before finality).POSTSimulate payment/v1/payments/{paymentId}/simulateSimulate a payment status transition. Available for test-coin assets only.POSTQuote payment fees/v1/payments/quoteReturns the platform fee, estimated network fee, and net amount for a payment of `amount` in `asset`, without creating anything. All monetary fields are integer strings in the asset's smallest unit.GETList payment transactions/v1/payments/{paymentId}/transactionsPaginated list of the on-chain transactions detected for a payment.Objects
Every endpoint page lists the fields of its own request and response inline. The full type surface — payment objects, quotes, transactions, redirects, and the status enumerations — is on one page: Objects & enums
Something unclear? payments@suward.com — we treat every integration question as a documentation defect.