Create payment

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.

POST/v1/paymentsAPI key

Request body

FieldTypeDescription
activationFlowSecondsoptionalintegerGrace 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).
amountoptionalstringMerchant 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.
assetoptionalAssetIDAsset 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
networkFeePayeroptionalFeePayerWho bears the network (gas) fee. Default merchant.
networkFeePayer values FeePayer
merchantcustomer
serviceFeePayeroptionalFeePayerWho bears the platform (service) fee. Default merchant.
serviceFeePayer values FeePayer
merchantcustomer
externalIdoptionalstringYour 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.
metadataoptionalobjectArbitrary 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.
paymentWindowSecondsoptionalintegerHow long the payment stays open for funding, in seconds. Optional; when omitted the project default applies. Range 300 (5 minutes) to 86400 (24 hours).
redirectConfigoptionalRedirectConfigDTOOptional "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
FieldTypeDescription
dataoptionalstringOpaque string passed through unchanged as the "data" query parameter on the return URL. Use it to carry your own session/order token.
paramsoptionalstring[]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
urloptionalstringBase "return to store" URL the customer is sent back to after paying.
underpaymentToleranceoptionalstringAmount 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.
webhookUrloptionalstringWebhook URL to receive this payment's events. Optional; overrides the project's default webhook URL for this payment only.

Response

201 Created

FieldTypeDescription
acceptedAtoptionalintegerUnix-milliseconds timestamp when the payment reached the accepted state (safe confirmations, balance credited). Null before acceptance.
activatedAtoptionalintegerUnix-milliseconds timestamp when the payment was activated and its payment window began counting. Null before activation.
activationFlowSecondsoptionalintegerResolved activation grace period, in seconds. Null when not configured.
addressoptionalstringOn-chain deposit address the customer must send funds to. Null until the payment is activated and an address is assigned.
amountoptionalstringInteger string in the asset's smallest unit.
amountConfirmedoptionalstringInteger string in the asset's smallest unit.
amountReceivedoptionalstringInteger string in the asset's smallest unit.
assetoptionalAssetIDAsset 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
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
confirmedAtoptionalintegerUnix-milliseconds timestamp when the payment reached finalization (confirmed). Null until confirmed; may revert if a chain reorg undoes the confirmation.
createdAtoptionalintegerUnix-milliseconds timestamp when the payment was created.
expiresAtoptionalintegerUnix-milliseconds timestamp when the payment window closes; the payment expires (fails) if it has not been paid by then.
externalIdoptionalstringMerchant's own identifier for this payment, echoed from creation. Null when none was provided.
feeoptionalstringPlatform fee: 0.4% of the amount, minimum $1 equivalent. Integer string in the asset's smallest unit.
idoptionalstringUnique Suward identifier of the payment. Use it in the payment endpoints (get, cancel, transactions) and as the checkout page path.
metadataoptionalobjectArbitrary key/value data attached by the merchant at creation, echoed back unchanged.
networkFeeoptionalstringEstimated on-chain (gas) cost, deducted from the received amount. Integer string in the asset's smallest unit.
quotedPriceoptionalstringUSD price of the asset locked at creation, decimal string. Fees are computed from this price at settlement, so the merchant's net is deterministic.
networkFeePayeroptionalFeePayerWho bears the network (gas) fee, echoed from creation.
networkFeePayer values FeePayer
merchantcustomer
serviceFeePayeroptionalFeePayerWho bears the platform (service) fee, echoed from creation.
serviceFeePayer values FeePayer
merchantcustomer
paymentWindowSecondsoptionalintegerResolved length of the payment window, in seconds.
projectIdoptionalstringIdentifier of the project that owns this payment.
redirectConfigoptionalRedirectConfigDTOReturn-to-store redirect configuration echoed from creation. Null when none was configured.
redirectConfig fields RedirectConfigDTO
FieldTypeDescription
dataoptionalstringOpaque string passed through unchanged as the "data" query parameter on the return URL. Use it to carry your own session/order token.
paramsoptionalstring[]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
urloptionalstringBase "return to store" URL the customer is sent back to after paying.
statusoptionalPaymentStatusEnumMain payment lifecycle status. See the status enum for the full meaning of each value.
status values PaymentStatusEnum
pendingacceptedsuccessfailed
subStatusoptionalPaymentSubStatusEnumFine-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
transactionsoptionalTransactionListPreview 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
FieldTypeDescription
hasMoreoptionalbooleanTrue when more transactions exist beyond this page. To fetch the next page, pass the last item's id as the lastId query parameter.
itemsoptionalTransactionResponse[]Page of transactions, ordered per the request's order parameter.
items fields TransactionResponse
FieldTypeDescription
acceptedAtoptionalintegerUnix-milliseconds timestamp when the transfer reached the accepted (safe) confirmation tier. Null before acceptance.
amountoptionalstringOn-chain transfer amount, an integer string in the asset's smallest unit (see CreatePaymentRequest.amount).
detectedAtoptionalintegerUnix-milliseconds timestamp when the transfer was first seen on-chain.
txHashoptionalstringOn-chain transaction hash of the transfer.
underpaymentToleranceoptionalstringInteger string in the asset's smallest unit.
updatedAtoptionalintegerUnix-milliseconds timestamp when the payment was last updated.
webhookUrloptionalstringWebhook URL that receives this payment's events, echoed from creation. Null when the project default webhook is used.
paymentPageUrloptionalstringAbsolute URL of the Suward-hosted checkout page where the customer pays this payment.

Errors

400 Bad Request401 Unauthorized500 Internal Server Error— each returns { errorCode, message, args? }. Codes, retries and limits: Errors & limits

All Payments endpoints

Request

terminal
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"}'

Response · 201 Created

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"
}

Illustrative values. Every field, type and status on this page is generated from the OpenAPI specification.

Something unclear? payments@suward.com — we treat every integration question as a documentation defect.