Simulate payment
Simulate a payment status transition. Available for test-coin assets only.
POST
/v1/payments/{paymentId}/simulateAPI keyPath parameters
| Field | Type | Description |
|---|---|---|
paymentIdrequired | string | Payment ID |
Request body
| Field | Type | Description |
|---|---|---|
amountoptional | string | Optional simulated received amount, integer string in the asset's smallest unit (see CreatePaymentRequest.amount). |
statusoptional | PaymentStatusEnum | Target main status. Required — status and subStatus are independent axes, both must be supplied. |
| ||
subStatusoptional | PaymentSubStatusEnum | Target sub-status (amount/detail axis). Required — status and subStatus are independent axes, both must be supplied. |
| ||
Response
200 OK
| 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/<payment_id>/simulate \ -H "X-Api-Key: $SUWARD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status":"success","subStatus":"completed"}'const response = await fetch('https://api.suward.com/v1/payments/<payment_id>/simulate', { method: 'POST', headers: { 'X-Api-Key': process.env.SUWARD_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "status": "success", "subStatus": "completed" }),});const data = await response.json();package main import ( "bytes" "fmt" "io" "net/http" "os") func main() { payload := []byte(`{"status":"success","subStatus":"completed"}`) req, _ := http.NewRequest("POST", "https://api.suward.com/v1/payments/<payment_id>/simulate", 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 = { "status": "success", "subStatus": "completed"} response = requests.post( 'https://api.suward.com/v1/payments/<payment_id>/simulate', headers={'X-Api-Key': os.environ['SUWARD_API_KEY']}, json=payload,)data = response.json()Response · 200 OK
{ "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.