Create payment

POST/v1/payments

Create 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.

Example request

A minimal request you can copy and run.

curl -X POST https://api.suward.com/v1/payments \
  -H "X-Api-Key: $SUWARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"1000000","asset":"USDT_ETHEREUM"}'

Request body

Name	Type	Required	Description
activationFlowSeconds	integer	no	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).
amount	string	no	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.
asset		no	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.
networkFeePayer		no	Who bears the network (gas) fee. Default merchant.
serviceFeePayer		no	Who bears the platform (service) fee. Default merchant.
externalId	string	no	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.
metadata	object	no	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.
paymentWindowSeconds	integer	no	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).
redirectConfig		no	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.
underpaymentTolerance	string	no	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.
webhookUrl	string	no	Webhook URL to receive this payment's events. Optional; overrides the project's default webhook URL for this payment only.

Request · JSON

{
  "amount": "1000000",
  "asset": "USDT_ETHEREUM"
}

Response

Name	Type	Required	Description
acceptedAt	integer	no	Unix-milliseconds timestamp when the payment reached the accepted state (safe confirmations, balance credited). Null before acceptance.
activatedAt	integer	no	Unix-milliseconds timestamp when the payment was activated and its payment window began counting. Null before activation.
activationFlowSeconds	integer	no	Resolved activation grace period, in seconds. Null when not configured.
address	string	no	On-chain deposit address the customer must send funds to. Null until the payment is activated and an address is assigned.
amount	string	no	Integer string in the asset's smallest unit.
amountConfirmed	string	no	Integer string in the asset's smallest unit.
amountReceived	string	no	Integer string in the asset's smallest unit.
asset		no	Asset the payment is denominated in, as an asset id-string (see GET /v1/assets). Null until an asset is selected for the payment.
confirmedAt	integer	no	Unix-milliseconds timestamp when the payment reached finalization (confirmed). Null until confirmed; may revert if a chain reorg undoes the confirmation.
createdAt	integer	no	Unix-milliseconds timestamp when the payment was created.
expiresAt	integer	no	Unix-milliseconds timestamp when the payment window closes; the payment expires (fails) if it has not been paid by then.
externalId	string	no	Merchant's own identifier for this payment, echoed from creation. Null when none was provided.
fee	string	no	Platform fee: 0.4% of the amount, minimum $1 equivalent. Integer string in the asset's smallest unit.
id	string	no	Unique Suward identifier of the payment. Use it in the payment endpoints (get, cancel, transactions) and as the checkout page path.
metadata	object	no	Arbitrary key/value data attached by the merchant at creation, echoed back unchanged.
networkFee	string	no	Estimated on-chain (gas) cost, deducted from the received amount. Integer string in the asset's smallest unit.
quotedPrice	string	no	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.
networkFeePayer		no	Who bears the network (gas) fee, echoed from creation.
serviceFeePayer		no	Who bears the platform (service) fee, echoed from creation.
paymentWindowSeconds	integer	no	Resolved length of the payment window, in seconds.
projectId	string	no	Identifier of the project that owns this payment.
redirectConfig		no	Return-to-store redirect configuration echoed from creation. Null when none was configured.
status		no	Main payment lifecycle status. See the status enum for the full meaning of each value.
subStatus		no	Fine-grained payment sub-status describing the current step or amount condition. See the sub-status enum for the full meaning of each value.
transactions		no	Preview page of the on-chain transactions detected for this payment (newest first). Use GET /v1/payments/{paymentId}/transactions for the full paginated list.
underpaymentTolerance	string	no	Integer string in the asset's smallest unit.
updatedAt	integer	no	Unix-milliseconds timestamp when the payment was last updated.
webhookUrl	string	no	Webhook URL that receives this payment's events, echoed from creation. Null when the project default webhook is used.
paymentPageUrl	string	no	Absolute URL of the Suward-hosted checkout page where the customer pays this payment.

Response · JSON

{
  "acceptedAt": 0,
  "activatedAt": 0,
  "activationFlowSeconds": 3600,
  "address": "0xabc…def",
  "amount": "100000000",
  "amountConfirmed": "100000000",
  "amountReceived": "100000000",
  "asset": "USDT_ETHEREUM",
  "confirmedAt": 0,
  "createdAt": 0,
  "expiresAt": 0,
  "externalId": "order_abc123",
  "fee": "1000000",
  "id": "obj_abc123",
  "metadata": {},
  "networkFee": "150000",
  "quotedPrice": "string",
  "networkFeePayer": "merchant",
  "serviceFeePayer": "merchant",
  "paymentWindowSeconds": 3600,
  "projectId": "obj_abc123",
  "redirectConfig": {},
  "status": "pending",
  "subStatus": "created",
  "transactions": {},
  "underpaymentTolerance": "0",
  "updatedAt": 0,
  "webhookUrl": "https://example.com/webhook",
  "paymentPageUrl": "string"
}

List payments Get payment