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 keyRequest body
| 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. | |||||||||||||||
| |||||||||||||||||
networkFeePayeroptional | FeePayer | Who bears the network (gas) fee. Default merchant. | |||||||||||||||
| |||||||||||||||||
serviceFeePayeroptional | FeePayer | Who bears the platform (service) fee. Default merchant. | |||||||||||||||
| |||||||||||||||||
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. | |||||||||||||||
| |||||||||||||||||
| Field | Type | Description |
|---|---|---|
dataoptional | string | Opaque string passed through unchanged as the "data" query parameter on the return URL. Use it to carry your own session/order token. |
paramsoptional | string[] | Which payment identifiers to append to the return URL as query parameters. Allowed values: "id" (the Suward payment id) and "externalId" (your identifier). |
| ||
urloptional | string | Base "return to store" URL the customer is sent back to after paying. |
underpaymentToleranceoptionalwebhookUrloptionalResponse
201 Created
| 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. | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
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. | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
serviceFeePayeroptional | FeePayer | Who bears the platform (service) fee, echoed from creation. | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
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. | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
| Field | Type | Description |
|---|---|---|
dataoptional | string | Opaque string passed through unchanged as the "data" query parameter on the return URL. Use it to carry your own session/order token. |
paramsoptional | string[] | Which payment identifiers to append to the return URL as query parameters. Allowed values: "id" (the Suward payment id) and "externalId" (your identifier). |
| ||
urloptional | string | Base "return to store" URL the customer is sent back to after paying. |
statusoptionalstatus values PaymentStatusEnum
pendingacceptedsuccessfailedsubStatusoptionalsubStatus values PaymentSubStatusEnum
createdactivatedawaitingPaymentconfirmingcompletedoverpaidunderpaidexpiredcancelledpartiallyPaidtransactionsoptionaltransactions fields TransactionList
| Field | Type | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
hasMoreoptional | 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. | |||||||||||||||
itemsoptional | TransactionResponse[] | Page of transactions, ordered per the request's order parameter. | |||||||||||||||
| |||||||||||||||||
| Field | Type | Description |
|---|---|---|
acceptedAtoptional | integer | Unix-milliseconds timestamp when the transfer reached the accepted (safe) confirmation tier. Null before acceptance. |
amountoptional | string | On-chain transfer amount, an integer string in the asset's smallest unit (see CreatePaymentRequest.amount). |
detectedAtoptional | integer | Unix-milliseconds timestamp when the transfer was first seen on-chain. |
txHashoptional | string | On-chain transaction hash of the transfer. |
underpaymentToleranceoptionalupdatedAtoptionalwebhookUrloptionalpaymentPageUrloptionalErrors
400 Bad Request401 Unauthorized500 Internal Server Error— each returns { errorCode, message, args? }. Codes, retries and limits: Errors & limits
Request
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"}'const response = await fetch('https://api.suward.com/v1/payments', { method: 'POST', headers: { 'X-Api-Key': process.env.SUWARD_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "amount": "1000000", "asset": "USDT_ETHEREUM" }),});const data = await response.json();package main import ( "bytes" "fmt" "io" "net/http" "os") func main() { payload := []byte(`{"amount":"1000000","asset":"USDT_ETHEREUM"}`) req, _ := http.NewRequest("POST", "https://api.suward.com/v1/payments", bytes.NewReader(payload)) req.Header.Set("X-Api-Key", os.Getenv("SUWARD_API_KEY")) req.Header.Set("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() data, _ := io.ReadAll(res.Body) fmt.Println(string(data))}import requests, os payload = { "amount": "1000000", "asset": "USDT_ETHEREUM"} response = requests.post( 'https://api.suward.com/v1/payments', headers={'X-Api-Key': os.environ['SUWARD_API_KEY']}, json=payload,)data = response.json()Response · 201 Created
{ "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.